Face Recognition Operations - Find Similar From Large Face List

Serviço:

Azure AI Services

Versão da API:

v1.2-preview.1

Dada a faceId da face da consulta, para pesquisar os rostos de aparência semelhante de uma Lista de Rostos Grandes. Um 'largeFaceListId' é criado pela Create Large Face List.
Dependendo da entrada, a lista de rostos semelhantes retornada contém faceIds ou persistedFaceIds classificadas por similaridade.

Localizar semelhante tem dois modos de trabalho, "matchPerson" e "matchFace". "matchPerson" é o modo padrão que ele tenta encontrar rostos da mesma pessoa possível usando limites internos da mesma pessoa. É útil encontrar outras fotos de uma pessoa conhecida. Observe que uma lista vazia será retornada se nenhum rosto passar pelos limites internos. O modo "matchFace" ignora os limites da mesma pessoa e retorna rostos semelhantes classificados de qualquer maneira, até mesmo a semelhança é baixa. Pode ser usado nos casos como pesquisar rostos de celebridades.

O 'recognitionModel' associado à faceId de consulta deve ser o mesmo que o 'recognitionModel' usado pela Lista de Rostos Grandes de destino.

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

Parâmetros de URI

Nome	Em	Obrigatório	Tipo	Description
apiVersion	path	True	string	Versão da API
endpoint	path	True	string uri	Pontos de extremidade dos Serviços Cognitivos com suporte (protocolo e nome do host, por exemplo: https://{resource-name}.cognitiveservices.azure.com).

Corpo da solicitação

Nome	Obrigatório	Tipo	Description
faceId	True	string	faceId da face da consulta. O usuário precisa chamar "Detectar" primeiro para obter uma faceId válida. Observe que essa faceId não é persistente e expirará 24 horas após a chamada de detecção.
largeFaceListId	True	string	Uma Lista de Rostos Grande exclusiva especificada pelo usuário existente, criada em "Criar Lista de Rostos Grandes". A Lista de Rostos Grandes contém um conjunto de persistedFaceIds que são persistentes e nunca expirarão.
maxNumOfCandidatesReturned		integer	O número de rostos semelhantes principais retornados. O intervalo válido é [1,1000]. O valor padrão é 20.
mode		FindSimilarMatchMode	Modo de pesquisa facial semelhante. Pode ser 'matchPerson' ou 'matchFace'. O valor padrão é 'matchPerson'.

Respostas

Nome	Tipo	Description
200 OK	FindSimilarResult[]	Uma chamada bem-sucedida retornará uma matriz dos rostos mais semelhantes representados em faceId se o parâmetro de entrada for faceIds ou persistedFaceId se o parâmetro de entrada for faceListId ou largeFaceListId.
Other Status Codes	FaceErrorResponse	Uma resposta de erro inesperada. Cabeçalhos x-ms-error-code: string

Segurança

Ocp-Apim-Subscription-Key

A chave secreta para sua assinatura do Azure AI Face.

Tipo: apiKey
Em: header

AADToken

O fluxo OAuth2 do Azure Active Directory

Tipo: oauth2
Flow: accessCode
URL de Autorização: https://api.example.com/oauth2/authorize
URL do Token: https://api.example.com/oauth2/token

Escopos

Nome	Description
https://cognitiveservices.azure.com/.default

Exemplos

Find Similar from LargeFaceList

Solicitação de exemplo

HTTP

POST {endpoint}/face/v1.2-preview.1/findsimilars

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

Resposta de exemplo

Código de status:

200

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

Definições

Nome	Description
FaceError	O objeto de erro. Para obter detalhes abrangentes sobre códigos de erro e mensagens retornadas pelo Serviço de Detecção Facial, consulte o seguinte link: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Uma resposta que contém detalhes do erro.
FindSimilarResult	Corpo da resposta para encontrar uma operação facial semelhante.

FaceError

O objeto de erro. Para obter detalhes abrangentes sobre códigos de erro e mensagens retornadas pelo Serviço de Detecção Facial, consulte o seguinte link: https://aka.ms/face-error-codes-and-messages.

Nome	Tipo	Description
code	string	Um de um conjunto definido pelo servidor de códigos de erro.
message	string	Uma representação legível pelo ser humano do erro.

FaceErrorResponse

Uma resposta que contém detalhes do erro.

Nome	Tipo	Description
error	FaceError	O objeto de erro.

FindSimilarResult

Corpo da resposta para encontrar uma operação facial semelhante.

Nome	Tipo	Description
confidence	number	Valor de confiança do candidato. Quanto maior a confiança, mais semelhante. Intervalo entre [0,1].
faceId	string	faceId do rosto do candidato quando encontrado por faceIds. faceId é criado por "Detectar" e expirará 24 horas após a chamada de detecção.
persistedFaceId	string	persistedFaceId do rosto do candidato quando encontrado por faceListId ou largeFaceListId. persistedFaceId na lista de rostos/lista de rostos grandes é persistente e não expirará.