Face Recognition Operations - Find Similar From Face List

Serviço:

Azure AI Services

Versão da API:

v1.2-preview.1

Dado o faceId da consulta, para pesquisar os rostos de aparência semelhante a partir de uma Lista de Rostos. Um 'faceListId' é criado por Create Face List.
Dependendo da entrada, a lista de rostos semelhantes retornados contém faceIds ou persistedFaceIds classificados por semelhança.

Find similar tem dois modos de trabalho, "matchPerson" e "matchFace". "matchPerson" é o modo padrão que 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 ultrapassar os limites internos. O modo "matchFace" ignora os limites da mesma pessoa e retorna rostos semelhantes classificados de qualquer maneira, mesmo que a semelhança seja baixa. Ele pode ser usado em casos como procurar rostos com aparência de celebridade.

O 'recognitionModel' associado ao faceId da consulta deve ser o mesmo que o 'recognitionModel' usado pela Face List de destino.

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

Parâmetros do URI

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

Corpo do Pedido

Name	Necessário	Tipo	Description
faceId	True	string	faceId da face da consulta. O usuário precisa chamar "Detetar" primeiro para obter um faceId válido. Observe que esse faceId não é persistente e expirará 24 horas após a chamada de deteção.
faceListId	True	string	Uma Lista de Rostos de Candidato exclusiva especificada pelo usuário existente, criada em "Criar Lista de Rostos". Face List contém um conjunto de FaceIds persistentes que são persistentes e nunca expirarão.
maxNumOfCandidatesReturned		integer	O número de rostos semelhantes retornou. O intervalo válido é [1, 1000]. O valor padrão é 20.
mode		FindSimilarMatchMode	Modo de pesquisa de rosto semelhante. Pode ser 'matchPerson' ou 'matchFace'. O valor padrão é 'matchPerson'.

Respostas

Name	Tipo	Description
200 OK	FindSimilarResult[]	Uma chamada bem-sucedida retorna uma matriz das faces mais semelhantes representadas 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 Ative Directory

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

Âmbitos

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

Exemplos

Find Similar from FaceList

Pedido de amostra

HTTP

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

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

Resposta da amostra

Código de estado:

200

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

Definições

Name	Description
FaceError	O objeto de erro. Para obter detalhes abrangentes sobre códigos de erro e mensagens retornadas pelo Face Service, consulte o seguinte link: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Uma resposta contendo detalhes do erro.
FindSimilarResult	Corpo de resposta para encontrar operação semelhante ao rosto.

FaceError

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

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

FaceErrorResponse

Uma resposta contendo detalhes do erro.

Name	Tipo	Description
error	FaceError	O objeto de erro.

FindSimilarResult

Corpo de resposta para encontrar operação semelhante ao rosto.

Name	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. O faceId é criado por "Detetar" e expirará 24 horas após a chamada de deteção.
persistedFaceId	string	persistedFaceId do rosto do candidato quando encontrado por faceListId ou largeFaceListId. persistedFaceId na lista de rostos/lista de rostos grande é persistente e não expirará.