Person Group Operations - Add Person Group Person Face

Служба:

Azure AI Services

Версия API:

v1.2-preview.1

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

Обратите внимание, что сохраненныйFaceId отличается от faceId, созданного параметром "Detect".

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

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

С использованием необязательных параметров:

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	Идентификатор контейнера. Шаблон регулярного выражения: ^[a-z0-9-_]+$
personId	path	True	string uuid	Идентификатор пользователя.
detectionModel	query		DetectionModel	Объект detectionModel, связанный с обнаруженными идентификаторами лиц. Поддерживаемые значения detectionModel включают "detection_01", "detection_02" и "detection_03". Значение по умолчанию — "detection_01".
targetFace	query		integer[]	Прямоугольник лица, указывающий целевое лицо, добавляемое пользователю, в формате targetFace=left, width, height.
userData	query		string	Предоставленные пользователем данные, подключенные к лицу. Ограничение размера равно 1K.

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

Media Types: "application/octet-stream"

Имя	Тип	Описание
imageContent	string	Изображение для анализа

Ответы

Имя	Тип	Описание
200 OK	AddFaceResult	Успешный вызов возвращает новый сохраненный интерфейсFaceId.
Other Status Codes	FaceErrorResponse	Непредвиденное сообщение об ошибке. Заголовки x-ms-error-code: string

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

Ocp-Apim-Subscription-Key

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

Тип: apiKey
В: header

AADToken

Поток OAuth2 Azure Active Directory

Тип: oauth2
Flow: accessCode
URL-адрес авторизации: https://api.example.com/oauth2/authorize
URL-адрес токена: https://api.example.com/oauth2/token

Области

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

Примеры

Add Face to PersonGroup Person

Образец запроса

HTTP

POST {endpoint}/face/v1.2-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>"

Пример ответа

Код состояния:

200

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

Определения

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

AddFaceResult

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

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

DetectionModel

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

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

FaceError

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

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

FaceErrorResponse

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

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