Face Recognition Operations - Find Similar

  • Referência
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

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á.