Face - Detect With Stream

  • Ссылка
Service:
Cognitive Services - Face
API Version:
1.0

Обнаруживает человеческие лица на изображении, возвращает прямоугольники с лицами и при необходимости с faceId, ориентирами и атрибутами.

  • Изображение не будет сохранено. На сервере будет храниться только извлеченная функция распознавания лиц. FaceId является идентификатором функции лица и будет использоваться в face - Identify, Face - Verify, and Face - Find Similar. Срок действия хранимых функций распознавания лиц истечет и будет удален в момент, указанный faceIdTimeToLive после первоначального вызова обнаружения.
  • Необязательные параметры включают faceId, ориентиры и атрибуты. Атрибуты включают возраст, пол, headPose, улыбку, лицеHair, очки, эмоции, волосы, макияж, окклюзию, аксессуары, размытие, экспозицию, шум, маску и качествоForRecognition. Некоторые результаты, возвращаемые для определенных атрибутов, могут быть не очень точными.
  • Поддерживаются формат JPEG, PNG, GIF (первый кадр) и BMP. Допустимый размер файла изображения составляет от 1 КБ до 6 МБ.
  • Для изображения можно вернуть до 100 лиц. Лица ранжируются по размеру прямоугольника от больших к маленьким.
  • Чтобы получить оптимальные результаты при запросе face - Identify, Face - Verify, and Face - Find Similar ('returnFaceId' is true), используйте лица, которые: frontal, clear и с минимальным размером 200x200 пикселей (100 пикселей между глазами).
  • Минимальный размер обнаруживаемого лица составляет 36 x 36 пикселей на изображении не более 1920 x 1080 пикселей. Изображения с размерами, превышающими 1920 x 1080 пикселей, потребуются пропорциональнее минимальный размер лица.
  • Можно указать различные значения detectionModel. Сведения об использовании и сравнении различных моделей обнаружения см. в разделе "Как указать модель обнаружения"
  • Предоставляются различные значения recognitionModel. Если требуются дальнейшие операции, такие как Verify, Identify, Find Similar, укажите модель распознавания с параметром RecognitionModel. Значение по умолчанию для recognitionModel — "recognition_01", если требуется последняя модель, укажите модель, необходимую в этом параметре. После указания обнаруженные идентификаторы faceId будут связаны с указанной моделью распознавания. Дополнительные сведения см. в разделе "Указание модели распознавания".
POST {Endpoint}/face/v1.0/detect
With optional parameters: 
POST {Endpoint}/face/v1.0/detect?overload=stream&returnFaceId={returnFaceId}&returnFaceLandmarks={returnFaceLandmarks}&returnFaceAttributes={returnFaceAttributes}&recognitionModel={recognitionModel}&returnRecognitionModel={returnRecognitionModel}&detectionModel={detectionModel}&faceIdTimeToLive={faceIdTimeToLive}

Параметры URI

Name In Required Type Description
Endpoint
 path True
  • string

Поддерживаемые конечные точки Cognitive Services (например, https://westus.api.cognitive.microsoft.comимя протокола и узла).
detectionModel
 query

Имя модели обнаружения. Модель обнаружения используется для обнаружения лиц на отправленном изображении. Имя модели обнаружения можно указать при выполнении face — Detect или (Large)FaceList — Add FaceGroup or (Large)PersonGroup — Add Face . Значение по умолчанию — "detection_01", если требуется другая модель, укажите ее явным образом.
faceIdTimeToLive
 query
  • integer

Количество секунд для кэшируемого идентификатора faceId. Поддерживаемый диапазон от 60 секунд до 86400 секунд. Значение по умолчанию — 86400 (24 часа).
recognitionModel
 query

Имя модели распознавания. Модель распознавания используется, когда признаки лица извлекаются и связаны с обнаруженными идентификаторами faceId, (Large)FaceList или (Large)PersonGroup. Имя модели распознавания можно указать при выполнении face — Detect или (Large)FaceList — Create или (Large)PersonGroup — Create. Значение по умолчанию — "recognition_01", если требуется последняя модель, укажите нужную модель явным образом.
returnFaceAttributes
 query
  • array

Анализ и возврат одного или нескольких указанных атрибутов лица в строке с разделителями-запятыми, например returnFaceAttributes=age, gender. Доступные атрибуты зависят от указанного объекта detectionModel. "detection_01" поддерживает возраст, пол, headPose, улыбку, лицоHair, очки, эмоции, волосы, макияж, аксессуары, размытие, экспозиция, шум и качествоForRecognition. Хотя "detection_02" не поддерживает атрибуты и "detection_03" поддерживает только маску и qualityForRecognition. Кроме того, qualityForRecognition поддерживается только в том случае, если параметр recognitionModel указан как "recognition_03" или "recognition_04". Обратите внимание, что каждый анализ атрибута лица имеет дополнительные вычислительные и временные затраты.
returnFaceId
 query
  • boolean

Значение, указывающее, должна ли операция возвращать идентификаторы faceId обнаруженных лиц.
returnFaceLandmarks
 query
  • boolean

Значение, указывающее, должна ли операция возвращать ориентиры обнаруженных лиц.
returnRecognitionModel
 query
  • boolean

Значение, указывающее, должна ли операция возвращать "recognitionModel" в ответ.

Заголовок запроса

Media Types: "application/octet-stream"

Name Required Type Description
Ocp-Apim-Subscription-Key True
  • string

Текст запроса

Media Types: "application/octet-stream"

Name Type Description
Image
  • object

Поток изображения.

Ответы

Name Type Description
200 OK

Успешный вызов возвращает массив записей лиц, ранжированных по размеру прямоугольника лица в порядке убывания. Пустой ответ указывает, что лица не обнаружены.
Other Status Codes

Ответ на ошибку.

Безопасность

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Примеры

Detect with stream example

Sample Request

POST {Endpoint}/face/v1.0/detect?overload=stream&returnFaceAttributes=age,gender,headPose,smile,facialHair,glasses,emotion,hair,makeup,occlusion,accessories,blur,exposure,noise&recognitionModel=recognition_01&returnRecognitionModel=True&detectionModel=detection_01


"{Image binary in base 64 format}"

Sample Response

Status code:
200 
[
  {
    "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
    "recognitionModel": "recognition_01",
    "faceRectangle": {
      "width": 78,
      "height": 78,
      "left": 394,
      "top": 54
    },
    "faceLandmarks": {
      "pupilLeft": {
        "x": 412.7,
        "y": 78.4
      },
      "pupilRight": {
        "x": 446.8,
        "y": 74.2
      },
      "noseTip": {
        "x": 437.7,
        "y": 92.4
      },
      "mouthLeft": {
        "x": 417.8,
        "y": 114.4
      },
      "mouthRight": {
        "x": 451.3,
        "y": 109.3
      },
      "eyebrowLeftOuter": {
        "x": 397.9,
        "y": 78.5
      },
      "eyebrowLeftInner": {
        "x": 425.4,
        "y": 70.5
      },
      "eyeLeftOuter": {
        "x": 406.7,
        "y": 80.6
      },
      "eyeLeftTop": {
        "x": 412.2,
        "y": 76.2
      },
      "eyeLeftBottom": {
        "x": 413,
        "y": 80.1
      },
      "eyeLeftInner": {
        "x": 418.9,
        "y": 78
      },
      "eyebrowRightInner": {
        "x": 4.8,
        "y": 69.7
      },
      "eyebrowRightOuter": {
        "x": 5.5,
        "y": 68.5
      },
      "eyeRightInner": {
        "x": 441.5,
        "y": 75
      },
      "eyeRightTop": {
        "x": 446.4,
        "y": 71.7
      },
      "eyeRightBottom": {
        "x": 447,
        "y": 75.3
      },
      "eyeRightOuter": {
        "x": 451.7,
        "y": 73.4
      },
      "noseRootLeft": {
        "x": 428,
        "y": 77.1
      },
      "noseRootRight": {
        "x": 435.8,
        "y": 75.6
      },
      "noseLeftAlarTop": {
        "x": 428.3,
        "y": 89.7
      },
      "noseRightAlarTop": {
        "x": 442.2,
        "y": 87
      },
      "noseLeftAlarOutTip": {
        "x": 424.3,
        "y": 96.4
      },
      "noseRightAlarOutTip": {
        "x": 446.6,
        "y": 92.5
      },
      "upperLipTop": {
        "x": 437.6,
        "y": 105.9
      },
      "upperLipBottom": {
        "x": 437.6,
        "y": 108.2
      },
      "underLipTop": {
        "x": 436.8,
        "y": 111.4
      },
      "underLipBottom": {
        "x": 437.3,
        "y": 114.5
      }
    },
    "faceAttributes": {
      "age": 71,
      "gender": "male",
      "smile": 0.88,
      "facialHair": {
        "moustache": 0.8,
        "beard": 0.1,
        "sideburns": 0.02
      },
      "glasses": "sunglasses",
      "headPose": {
        "roll": 2.1,
        "yaw": 3,
        "pitch": 1.6
      },
      "emotion": {
        "anger": 0.575,
        "contempt": 0,
        "disgust": 0.006,
        "fear": 0.008,
        "happiness": 0.394,
        "neutral": 0.013,
        "sadness": 0,
        "surprise": 0.004
      },
      "hair": {
        "bald": 0,
        "invisible": false,
        "hairColor": [
          {
            "color": "brown",
            "confidence": 1
          },
          {
            "color": "blond",
            "confidence": 0.88
          },
          {
            "color": "black",
            "confidence": 0.48
          },
          {
            "color": "other",
            "confidence": 0.11
          },
          {
            "color": "gray",
            "confidence": 0.07
          },
          {
            "color": "red",
            "confidence": 0.03
          }
        ]
      },
      "makeup": {
        "eyeMakeup": true,
        "lipMakeup": false
      },
      "occlusion": {
        "foreheadOccluded": false,
        "eyeOccluded": false,
        "mouthOccluded": false
      },
      "accessories": [
        {
          "type": "headWear",
          "confidence": 0.99
        },
        {
          "type": "glasses",
          "confidence": 1
        },
        {
          "type": "mask",
          "confidence": 0.87
        }
      ],
      "blur": {
        "blurLevel": "Medium",
        "value": 0.51
      },
      "exposure": {
        "exposureLevel": "GoodExposure",
        "value": 0.55
      },
      "noise": {
        "noiseLevel": "Low",
        "value": 0.12
      }
    }
  }
]

Определения

Accessory

Элемент аксессуара и соответствующий уровень достоверности.
AccessoryType

Тип аксессуара
APIError

Сведения об ошибке, возвращаемые API
Blur

Свойства, описывающие наличие размытия в изображении.
BlurLevel

Значение перечисления, указывающее уровень размытости.
Coordinate

Координаты в изображении
DetectedFace

Обнаруженный объект Face.
DetectionModel

Имя модели обнаружения. Модель обнаружения используется для обнаружения лиц на отправленном изображении. Имя модели обнаружения можно указать при выполнении face — Detect or (Large)FaceList — Add FaceGroup or (Large)PersonGroup — Add Face ( Add Face). Значение по умолчанию — "detection_01", если требуется другая модель, явно укажите ее.
Emotion

Свойства, описывающие эмоции лица в виде уверенности в диапазоне от 0 до 1.
Error

Текст ошибки.
Exposure

Свойства, описывающие уровень экспозиции изображения.
ExposureLevel

Значение перечисления, указывающее уровень экспозиции.
FaceAttributes

Атрибуты лиц
FaceLandmarks

Коллекция из 27 точек лиц ориентиры, указывающие на важные позиции компонентов лица.
FaceRectangle

Прямоугольник, в котором можно найти лицо
FacialHair

Свойства, описывающие атрибуты волос на лице.
Gender

Возможный пол лица.
GlassesType

Очки введите, если какой-либо из лиц.
Hair

Свойства, описывающие атрибуты волос.
HairColor

Цвет волос и связанная уверенность
HairColorType

Имя цвета волос.
HeadPose

Свойства, указывающие на положение головы лица.
Makeup

Свойства, описывающие присутствие макияжа на данном лице.
Mask

Свойства, описывающие наличие маски на данном лице.
MaskType

Тип маски, если какой-либо из лиц
Noise

Свойства, описывающие уровень шума изображения.
NoiseLevel

Значение перечисления, указывающее уровень шума.
Occlusion

Свойства, описывающие окклюзии на данном лице.
QualityForRecognition

Значение перечисления, указывающее качество изображения для распознавания.
RecognitionModel

Имя модели распознавания. Модель распознавания используется, когда функции распознавания извлекаются и связаны с обнаруженными faceIds, (Large)FaceList или (Large)PersonGroup. Имя модели распознавания можно указать при выполнении face — Detect or (Large)FaceList — Create or (Large)PersonGroup — Create. Значение по умолчанию — "recognition_01", если требуется последняя модель, явно укажите нужную модель.

Accessory

Элемент аксессуара и соответствующий уровень достоверности.

Name Type Description
confidence
  • number

Уровень достоверности аксессуара
type

Тип аксессуара

AccessoryType

Тип аксессуара

Name Type Description
glasses
  • string
headWear
  • string
mask
  • string

APIError

Сведения об ошибке, возвращаемые API

Name Type Description
error

Текст ошибки.

Blur

Свойства, описывающие наличие размытия в изображении.

Name Type Description
blurLevel

Значение перечисления, указывающее уровень размытости.
value
  • number

Число, указывающее уровень размытости в диапазоне от 0 до 1.

BlurLevel

Значение перечисления, указывающее уровень размытости.

Name Type Description
High
  • string
Low
  • string
Medium
  • string

Coordinate

Координаты в изображении

Name Type Description
x
  • number

Горизонтальный компонент в пикселях.
y
  • number

Вертикальный компонент (в пикселях).

DetectedFace

Обнаруженный объект Face.

Name Type Default Value Description
faceAttributes

Атрибуты лиц
faceId
  • string
faceLandmarks

Коллекция из 27 точек лиц ориентиры, указывающие на важные позиции компонентов лица.
faceRectangle

Прямоугольник, в котором можно найти лицо
recognitionModel recognition_01

Имя модели распознавания. Модель распознавания используется, когда функции распознавания извлекаются и связаны с обнаруженными faceIds, (Large)FaceList или (Large)PersonGroup. Имя модели распознавания можно указать при выполнении face — Detect or (Large)FaceList — Create or (Large)PersonGroup — Create. Значение по умолчанию — "recognition_01", если требуется последняя модель, явно укажите нужную модель.

DetectionModel

Имя модели обнаружения. Модель обнаружения используется для обнаружения лиц на отправленном изображении. Имя модели обнаружения можно указать при выполнении face — Detect or (Large)FaceList — Add FaceGroup or (Large)PersonGroup — Add Face ( Add Face). Значение по умолчанию — "detection_01", если требуется другая модель, явно укажите ее.

Name Type Description
detection_01
  • string
detection_02
  • string
detection_03
  • string

Emotion

Свойства, описывающие эмоции лица в виде уверенности в диапазоне от 0 до 1.

Name Type Description
anger
  • number

Число от 0 до 1, указывающее уровень достоверности, связанный со свойством.
contempt
  • number

Число от 0 до 1, указывающее уровень достоверности, связанный со свойством.
disgust
  • number

Число от 0 до 1, указывающее уровень достоверности, связанный со свойством.
fear
  • number

Число от 0 до 1, указывающее уровень достоверности, связанный со свойством.
happiness
  • number

Число от 0 до 1, указывающее уровень достоверности, связанный со свойством.
neutral
  • number

Число от 0 до 1, указывающее уровень достоверности, связанный со свойством.
sadness
  • number

Число от 0 до 1, указывающее уровень достоверности, связанный со свойством.
surprise
  • number

Число от 0 до 1, указывающее уровень достоверности, связанный со свойством.

Error

Текст ошибки.

Name Type Description
code
  • string
message
  • string

Exposure

Свойства, описывающие уровень экспозиции изображения.

Name Type Description
exposureLevel

Значение перечисления, указывающее уровень экспозиции.
value
  • number

Число, указывающее уровень экспозиции в диапазоне от 0 до 1. [0, 0,25) находится под воздействием. [0,25, 0,75) является хорошим воздействием. [0,75, 1] превышает экспозицию.

ExposureLevel

Значение перечисления, указывающее уровень экспозиции.

Name Type Description
GoodExposure
  • string
OverExposure
  • string
UnderExposure
  • string

FaceAttributes

Атрибуты лиц

Name Type Description
accessories

Свойства, описывающие любые аксессуары на данном лице.
age
  • number

Возраст в годах
blur

Свойства, описывающие наличие размытия в изображении.
emotion

Свойства, описывающие эмоции лица в виде уверенности в диапазоне от 0 до 1.
exposure

Свойства, описывающие уровень экспозиции изображения.
facialHair

Свойства, описывающие атрибуты волос на лице.
gender

Возможный пол лица.
glasses

Очки введите, если какой-либо из лиц.
hair

Свойства, описывающие атрибуты волос.
headPose

Свойства, указывающие на положение головы лица.
makeup

Свойства, описывающие присутствие макияжа на данном лице.
mask

Свойства, описывающие наличие маски на данном лице.
noise

Свойства, описывающие уровень шума изображения.
occlusion

Свойства, описывающие окклюзии на данном лице.
qualityForRecognition

Свойства, описывающие общее качество изображения относительно того, является ли изображение, используемое в обнаружении, имеет достаточное качество, чтобы попытаться распознать лица.
smile
  • number

Интенсивность улыбки, число между [0,1]

FaceLandmarks

Коллекция из 27 точек лиц ориентиры, указывающие на важные позиции компонентов лица.

Name Type Description
eyeLeftBottom

Координаты в изображении
eyeLeftInner

Координаты в изображении
eyeLeftOuter

Координаты в изображении
eyeLeftTop

Координаты в изображении
eyeRightBottom

Координаты в изображении
eyeRightInner

Координаты в изображении
eyeRightOuter

Координаты в изображении
eyeRightTop

Координаты в изображении
eyebrowLeftInner

Координаты в изображении
eyebrowLeftOuter

Координаты в изображении
eyebrowRightInner

Координаты в изображении
eyebrowRightOuter

Координаты в изображении
mouthLeft

Координаты в изображении
mouthRight

Координаты в изображении
noseLeftAlarOutTip

Координаты в изображении
noseLeftAlarTop

Координаты в изображении
noseRightAlarOutTip

Координаты в изображении
noseRightAlarTop

Координаты в изображении
noseRootLeft

Координаты в изображении
noseRootRight

Координаты в изображении
noseTip

Координаты в изображении
pupilLeft

Координаты в изображении
pupilRight

Координаты в изображении
underLipBottom

Координаты в изображении
underLipTop

Координаты в изображении
upperLipBottom

Координаты в изображении
upperLipTop

Координаты в изображении

FaceRectangle

Прямоугольник, в котором можно найти лицо

Name Type Description
height
  • integer

Высота прямоугольника в пикселях.
left
  • integer

Расстояние от левого края, если изображение до левого края прямоугольника в пикселях.
top
  • integer

Расстояние от верхнего края, если изображение до верхнего края прямоугольника в пикселях.
width
  • integer

Ширина прямоугольника в пикселях.

FacialHair

Свойства, описывающие атрибуты волос на лице.

Name Type Description
beard
  • number

Число от 0 до 1, указывающее уровень достоверности, связанный со свойством.
moustache
  • number

Число от 0 до 1, указывающее уровень достоверности, связанный со свойством.
sideburns
  • number

Число от 0 до 1, указывающее уровень достоверности, связанный со свойством.

Gender

Возможный пол лица.

Name Type Description
female
  • string
male
  • string

GlassesType

Очки введите, если какой-либо из лиц.

Name Type Description
noGlasses
  • string
readingGlasses
  • string
sunglasses
  • string
swimmingGoggles
  • string

Hair

Свойства, описывающие атрибуты волос.

Name Type Description
bald
  • number

Число, описывающее уровень достоверности того, является ли человек лысым.
hairColor

Массив цветов кандидатов и уровень достоверности в присутствии каждого из них.
invisible
  • boolean

Логическое значение, описывающее, видимы ли волосы на изображении.

HairColor

Цвет волос и связанная уверенность

Name Type Description
color

Имя цвета волос.
confidence
  • number

Уровень достоверности цвета

HairColorType

Имя цвета волос.

Name Type Description
black
  • string
blond
  • string
brown
  • string
gray
  • string
other
  • string
red
  • string
unknown
  • string
white
  • string

HeadPose

Свойства, указывающие на положение головы лица.

Name Type Description
pitch
  • number
roll
  • number
yaw
  • number

Makeup

Свойства, описывающие присутствие макияжа на данном лице.

Name Type Description
eyeMakeup
  • boolean

Логическое значение, описывающее, присутствует ли макияж глаз на лице.
lipMakeup
  • boolean

Логическое значение, описывающее, присутствует ли макияж губ на лице.

Mask

Свойства, описывающие наличие маски на данном лице.

Name Type Description
noseAndMouthCovered
  • boolean

Логическое значение, указывающее, покрыты ли нос и рот.
type

Тип маски, если какой-либо из лиц

MaskType

Тип маски, если какой-либо из лиц

Name Type Description
faceMask
  • string
noMask
  • string
otherMaskOrOcclusion
  • string
uncertain
  • string

Noise

Свойства, описывающие уровень шума изображения.

Name Type Description
noiseLevel

Значение перечисления, указывающее уровень шума.
value
  • number

Число, указывающее уровень шума в диапазоне от 0 до 1. [0, 0,25) находится под воздействием. [0,25, 0,75) является хорошим воздействием. [0,75, 1] превышает экспозицию. [0, 0,3) — низкий уровень шума. [0,3, 0,7) — средний уровень шума. [0,7, 1] — высокий уровень шума.

NoiseLevel

Значение перечисления, указывающее уровень шума.

Name Type Description
High
  • string
Low
  • string
Medium
  • string

Occlusion

Свойства, описывающие окклюзии на данном лице.

Name Type Description
eyeOccluded
  • boolean

Логическое значение, указывающее, являются ли глаза occluded.
foreheadOccluded
  • boolean

Логическое значение, указывающее, окклюзуется ли лоб.
mouthOccluded
  • boolean

Логическое значение, указывающее, является ли рот occluded.

QualityForRecognition

Значение перечисления, указывающее качество изображения для распознавания.

Name Type Description
High
  • string
Low
  • string
Medium
  • string

RecognitionModel

Имя модели распознавания. Модель распознавания используется, когда функции распознавания извлекаются и связаны с обнаруженными faceIds, (Large)FaceList или (Large)PersonGroup. Имя модели распознавания можно указать при выполнении face — Detect or (Large)FaceList — Create or (Large)PersonGroup — Create. Значение по умолчанию — "recognition_01", если требуется последняя модель, явно укажите нужную модель.

Name Type Description
recognition_01
  • string
recognition_02
  • string
recognition_03
  • string
recognition_04
  • string