Face Recognition Operations - Find Similar

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 matriz faceId. Uma matriz faceId contém os rostos criados pelo Detect.
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 matriz faceId 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.
faceIds	True	string[]	Uma matriz de faceIds candidatas. Todos eles são criados por "Detectar" e as faceIds expirarão 24 horas após a chamada de detecção. O número de faceIds é limitado a 1000.
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 among Face IDs

Solicitação de exemplo

HTTP

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

{
  "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
  "maxNumOfCandidatesReturned": 3,
  "mode": "matchPerson",
  "faceIds": [
    "015839fb-fbd9-4f79-ace9-7675fc2f1dd9",
    "be386ab3-af91-4104-9e6d-4dae4c9fddb7"
  ]
}

Resposta de exemplo

Código de status:

200

[
  {
    "confidence": 0.9,
    "persistedFaceId": "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á.