Face Recognition Operations - Find Similar From Face List

Служба:: Azure AI Services

Версия API:: v1.2

При выполнении запроса faceId для поиска похожих лиц из списка лиц. Элемент faceListId создается с помощью создания списка лиц.
В зависимости от входных данных возвращаемый список лиц содержит faceIds или сохраненныеFaceIds, ранжированные по сходству.

Найдите аналогичные режимы работы, "matchPerson" и "matchFace". "matchPerson" — это режим по умолчанию, который пытается найти лица одного и того же человека, как это возможно, с помощью внутренних пороговых значений одного и того же человека. Полезно найти другие фотографии известного человека. Обратите внимание, что пустой список будет возвращен, если лица не передают внутренние пороговые значения. Режим matchFace игнорирует пороговые значения одного и того же человека и возвращает аналогичные лица в любом случае, даже сходство низко. Его можно использовать в таких случаях, как поиск знаменитостей глядя лица.

Идентификатор распознавания лиц, связанный с запросом faceId, должен совпадать с идентификатором распознавания, используемым целевым списком лиц.

POST {endpoint}/face/{apiVersion}/findsimilars

Параметры URI

Имя	В	Обязательно	Тип	Описание
apiVersion	path	True	string	Версия API
endpoint	path	True	string (uri)	Поддерживаемые конечные точки Cognitive Services (протокол и имя узла, например https://{имя ресурса}.cognitiveservices.azure.com).

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

Имя	Обязательно	Тип	Описание
faceId	True	string (uuid)	faceId лица запроса. Пользователю сначала необходимо вызвать "Detect", чтобы получить допустимый faceId. Обратите внимание, что этот faceId не сохраняется и истекает 24 часа после вызова обнаружения.
faceListId	True	string	Существующий уникальный список лиц, указанный пользователем, созданный в разделе "Создание списка лиц". Список лиц содержит набор сохраненныхFaceIds, которые сохраняются и никогда не истекают.
maxNumOfCandidatesReturned		integer (int32) minimum: 1 maximum: 1000	Число возвращаемых сверху похожих лиц. Допустимый диапазон — [1, 1000]. Значение по умолчанию — 20.
mode		FindSimilarMatchMode	Аналогичный режим поиска лиц. Это может быть "matchPerson" или "matchFace". Значение по умолчанию — matchPerson.

Ответы

Имя	Тип	Описание
200 OK	FindSimilarResult[]	Успешный вызов возвращает массив наиболее похожих лиц, представленных в faceId, если входной параметр faceId или persistedFaceId, если входной параметр faceListId или largeFaceListId.
Other Status Codes	FaceErrorResponse	Непредвиденное сообщение об ошибке. Заголовки x-ms-error-code: string

Имя

Тип

Описание

200 OK

FindSimilarResult[]

Успешный вызов возвращает массив наиболее похожих лиц, представленных в faceId, если входной параметр faceId или persistedFaceId, если входной параметр faceListId или largeFaceListId.

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

Примеры

Find Similar from FaceList

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

HTTP

POST {endpoint}/face/v1.2/findsimilars

{
  "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
  "maxNumOfCandidatesReturned": 3,
  "mode": "matchPerson",
  "faceListId": "your_face_list_id"
}

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

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

[
  {
    "confidence": 0.8,
    "persistedFaceId": "015839fb-fbd9-4f79-ace9-7675fc2f1dd9"
  }
]

Определения

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

FaceError

Object

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

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

FaceErrorResponse

Object

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

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

FindSimilarResult

Object

Текст ответа для поиска аналогичной операции распознавания лиц.

Имя	Тип	Описание
confidence	number (float) minimum: 0 maximum: 1	Достоверность значения кандидата. Чем выше уверенность, тем больше похоже. Диапазон от [0,1].
faceId	string (uuid)	faceId кандидата лица при поиске по faceIds. faceId создается с помощью функции "Обнаружение" и истекает через 24 часа после вызова обнаружения.
persistedFaceId	string (uuid)	сохраняемый идентификатор лица кандидата при поиске по faceListId или largeFaceListId. сохраняемый интерфейсFaceId в списке лиц или большом списке лиц сохраняется и не истекает.