Person Directory Operations - Add Person Face From Url

Служба:

Azure AI Services

Версия API:

v1.2-preview.1

Добавьте лицо к человеку (см. раздел "Создание пользователя") для идентификации или проверки лиц.
Чтобы справиться с изображением, содержащим несколько лиц, входное лицо можно указать как изображение с прямоугольником targetFace. Он возвращает сохраненныйFaceId, представляющий добавленное лицо. Изображение не будет сохранено. Только извлеченные функции лица будут храниться на сервере, пока не будет вызван каталог person "Delete Person Face" или "Delete Person".

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

• • Каждый пользователь может содержать до 248 лиц.
  • Более высокое качество изображения лица означает лучшую точность распознавания. Рассмотрим высококачественные лица: фронтальные, четкие и размер лица составляет 200x200 пикселей (100 пикселей между глазами) или больше.
  • Поддерживаются формат JPEG, PNG, GIF (первый кадр) и BMP. Допустимый размер файла изображения составляет от 1 КБ до 6 МБ.
  • Прямоугольник targetFace должен содержать одно лицо. Ноль или несколько лиц будут рассматриваться как ошибка. Если предоставленный прямоугольник targetFace не возвращается из параметра "Обнаружение", нет гарантии успешного обнаружения и добавления лица.
  • Из обнаруживаемого размера лица (36x36 – 4096x4096 пикселей), большого размера головы или больших окклюзий произойдет сбой.
  • Минимальный размер обнаруживаемого лица составляет 36x36 пикселей на изображении не более 1920x1080 пикселей. Изображения с измерениями выше 1920x1080 пикселей потребуется пропорционально больше минимального размера лица.
  • Можно указать различные значения detectionModel. Сведения об использовании и сравнении различных моделей обнаружения см. в здесь.
  • Добавление и удаление лиц в один и тот же человек будет обрабатываться последовательно. Добавление и удаление лиц в разные лица обрабатываются параллельно.
  • Выполнение этой операции занимает длительное время. Используйте заголовок ответа "Operation-Location" для определения успешного распространения операции AddFace для будущих запросов на "Идентификация". Дополнительные сведения о Operation-Locations см. в разделе "Получение состояния операции распознавания лиц".

POST {endpoint}/face/{apiVersion}/persons/{personId}/recognitionModels/{recognitionModel}/persistedfaces

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

POST {endpoint}/face/{apiVersion}/persons/{personId}/recognitionModels/{recognitionModel}/persistedfaces?_overload=addPersonFaceFromUrl&targetFace={targetFace}&detectionModel={detectionModel}&userData={userData}

Параметры URI

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

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

Имя	Обязательно	Тип	Описание
url	True	string (uri)	URL-адрес входного изображения.

Ответы

Имя	Тип	Описание
202 Accepted	AddFaceResult	Успешный вызов возвращает пустой текст ответа. Служба приняла запрос и начнет обработку в ближайшее время. Клиент может запрашивать состояние операции и результат, используя URL-адрес, указанный в заголовке ответа Operation-Location. Срок действия URL-адреса истекает через 48 часов. Заголовки Location: string operation-Location: string
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 PersonDirectory Person from Url

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

HTTP

POST {endpoint}/face/v1.2-preview.1/persons/85c0c630-c9c9-40f8-8a4e-f9ae4f926ea5/recognitionModels/recognition_01/persistedfaces?_overload=addPersonFaceFromUrl&targetFace=10,10,100,100&detectionModel=detection_01&userData=your_user_data

{
  "url": "https://microsoft.com/example.jpg"
}

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

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

202

location: https://contoso.com/operationstatus
operation-Location: https://contoso.com/operationstatus

{
  "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	Ответ, содержащий сведения об ошибке.
RecognitionModel	Модель распознавания лица.

AddFaceResult

Object

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

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

DetectionModel

Перечисление

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

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

FaceError

Object

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

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

FaceErrorResponse

Object

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

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

RecognitionModel

Перечисление

Модель распознавания лица.

Значение	Описание
recognition_01	Модель распознавания по умолчанию для "Обнаружение". Все эти лица, созданные до марта 2019 года, связаны с этой моделью распознавания.
recognition_02	Модель распознавания выпущена в марте 2019 года.
recognition_03	Модель распознавания выпущена в мае 2020 года.
recognition_04	Модель распознавания, выпущенная в феврале 2021 года. Рекомендуется использовать эту модель распознавания для повышения точности распознавания.