Person Group Operations - Add Person Group Person Face

Service:

Azure AI Services

API Version:

v1.1-preview.1

Добавление лица к человеку в группу пользователей для идентификации или проверки лица.
Чтобы иметь дело с изображением, содержащим несколько лиц, входной лицевой элемент можно указать как изображение с прямоугольником targetFace. Он возвращает значение persistedFaceId, представляющее добавленное лицо. Образ не будет сохранен. Только извлеченные функции распознавания лиц будут храниться на сервере до тех пор, пока не будут вызваны "Удалить лицо пользователя группы пользователей", "Удалить пользователя группы пользователей" или "Удалить группу пользователей".

Обратите внимание, что persistedFaceId отличается от faceId, созданного с помощью "Detect".

• • Более высокое качество изображения лица означает лучшую точность распознавания. Пожалуйста, рассмотрите высококачественные лица: фронтальные, четкие и размер лица 200 x 200 пикселей (100 пикселей между глазами) или больше.
  • Каждая запись может содержать до 248 лиц.
  • Поддерживаются JPEG, PNG, GIF (первый кадр) и формат BMP. Допустимый размер файла изображения составляет от 1 КБ до 6 МБ.
  • Прямоугольник targetFace должен содержать одну грань. Ноль или несколько лиц будут рассматриваться как ошибка. Если предоставленный прямоугольник targetFace не возвращается из элемента "Detect", нет никакой гарантии для успешного обнаружения и добавления лица.
  • Если определить размер лица (36x36–4096 x 4096 пикселей), большой размер головы или большие окклюзии вызовут сбои.
  • Минимальный размер обнаруживаемого лица составляет 36 x 36 пикселей на изображении, не превышающем 1920 x 1080 пикселей. Изображениям с размерами выше 1920 x 1080 пикселей потребуется пропорционально больший минимальный размер лица.
  • Можно указать различные значения detectionModel. Сведения об использовании и сравнении различных моделей обнаружения см. в статье https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-detection-model

POST {endpoint}/face/{apiVersion}/persongroups/{personGroupId}/persons/{personId}/persistedfaces

With optional parameters:

POST {endpoint}/face/{apiVersion}/persongroups/{personGroupId}/persons/{personId}/persistedfaces?_overload=addPersonGroupPersonFace&targetFace={targetFace}&detectionModel={detectionModel}&userData={userData}

Параметры URI

Имя	В	Обязательно	Тип	Описание
apiVersion	path	True	string	Версия API
endpoint	path	True	string uri	Поддерживаемые конечные точки Cognitive Services (протокол и имя узла, например: https://{имя_ресурса}.cognitiveservices.azure.com).
personGroupId	path	True	string	Идентификатор контейнера. Regex pattern: ^[a-z0-9-_]+$
personId	path	True	string uuid	Идентификатор пользователя.
detectionModel	query		DetectionModel	Объект detectionModel, связанный с обнаруженными идентификаторами faceId. Поддерживаемые значения detectionModel включают detection_01, detection_02 и detection_03. Значение по умолчанию — "detection_01".
targetFace	query		integer[]	Прямоугольник лица, указывающий целевое лицо, добавляемое к человеку, в формате "targetFace=left,top,width,height".
userData	query		string	Предоставленные пользователем данные, прикрепленные к лицу. Предельный размер — 1K.

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

Media Types: "application/octet-stream"

Имя	Тип	Описание
imageContent	string	Образ, который требуется проанализировать

Ответы

Имя	Тип	Описание
200 OK	AddFaceResult	При успешном вызове возвращается новый объект persistedFaceId.
Other Status Codes	FaceErrorResponse	Непредвиденное сообщение об ошибке. Headers x-ms-error-code: string

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

Ocp-Apim-Subscription-Key

Секретный ключ для подписки azure AI Face.

Type: apiKey
In: header

AADToken

Поток OAuth2 в Azure Active Directory

Type: oauth2
Flow: accessCode
Authorization URL: https://api.example.com/oauth2/authorize
Token URL: https://api.example.com/oauth2/token

Scopes

Имя	Описание
https://cognitiveservices.azure.com/.default

Примеры

Add Face to PersonGroup Person

Sample Request

HTTP

POST {endpoint}/face/v1.1-preview.1/persongroups/your_person_group_id/persons/25985303-c537-4467-b41d-bdb45cd95ca1/persistedfaces?_overload=addPersonGroupPersonFace&targetFace=10,10,100,100&detectionModel=detection_01&userData=your_user_data

"<your-image-bytes-here>"

Sample Response

Status code:

200

{
  "persistedFaceId": "43897a75-8d6f-42cf-885e-74832febb055"
}

Определения

Имя	Описание
AddFaceResult	Текст ответа для добавления лица.
DetectionModel	Объект detectionModel, связанный с обнаруженными идентификаторами faceId. Поддерживаемые значения detectionModel включают detection_01, detection_02 и detection_03. Значение по умолчанию — "detection_01".
FaceError	Объект ошибки. Подробные сведения о кодах ошибок и сообщениях, возвращаемых службой распознавания лиц, см. по следующей ссылке: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Ответ, содержащий сведения об ошибке.

AddFaceResult

Текст ответа для добавления лица.

Имя	Тип	Описание
persistedFaceId	string	Сохраненный идентификатор лица добавленного лица, который сохраняется и не истечет. Отличается от faceId, который создается в "Detect" и истекает через 24 часа после вызова обнаружения.

DetectionModel

Объект detectionModel, связанный с обнаруженными идентификаторами faceId. Поддерживаемые значения detectionModel включают detection_01, detection_02 и detection_03. Значение по умолчанию — "detection_01".

Имя	Тип	Описание
detection_01	string	Модель обнаружения по умолчанию. Рекомендуется для обнаружения лиц, близких к переднему краю. В сценариях с исключительно большими углами (положение головы), лицами с заключителями или неправильной ориентацией изображения лица в таких случаях могут не обнаруживаться.
detection_02	string	Модель обнаружения, выпущенная в мае 2019 года с улучшенной точностью, особенно на небольших, боковых и размытых лицах.
detection_03	string	Модель обнаружения, выпущенная в феврале 2021 г. с улучшенной точностью, особенно на небольших лицах.

FaceError

Объект ошибки. Подробные сведения о кодах ошибок и сообщениях, возвращаемых службой распознавания лиц, см. по следующей ссылке: https://aka.ms/face-error-codes-and-messages.

Имя	Тип	Описание
code	string	Один из серверных наборов кодов ошибок.
message	string	Понятное представление ошибки.

FaceErrorResponse

Ответ, содержащий сведения об ошибке.

Имя	Тип	Описание
error	FaceError	Объект ошибки.