Face Recognition Operations - Find Similar

Service:

Azure AI Services

API Version:

v1.1-preview.1

Dado el faceId de la cara de consulta, para buscar las caras similares de una matriz faceId. Una matriz faceId contiene las caras creadas por Detect.
Dependiendo de la entrada, la lista de caras similares devuelta contiene faceIds o persistedFaceIds clasificados por similitud.

Buscar similar tiene dos modos de trabajo, "matchPerson" y "matchFace". "matchPerson" es el modo predeterminado que intenta encontrar caras de la misma persona como sea posible mediante umbrales internos de la misma persona. Es útil encontrar otras fotos de una persona conocida. Tenga en cuenta que se devolverá una lista vacía si ninguna cara supera los umbrales internos. El modo "matchFace" omite los umbrales de la misma persona y devuelve caras similares clasificadas de todos modos, incluso la similitud es baja. Se puede usar en los casos como buscar caras con celebridad.

El elemento "recognitionModel" asociado con el faceId de consulta debe ser el mismo que el "recognitionModel" usado por la matriz faceId de destino.

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

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
apiVersion	path	True	string	Versión de la API
endpoint	path	True	string uri	Puntos de conexión de Cognitive Services admitidos (protocolo y nombre de host, por ejemplo: https://{resource-name}.cognitiveservices.azure.com).

Cuerpo de la solicitud

Nombre	Requerido	Tipo	Description
faceId	True	string	faceId de la cara de consulta. El usuario debe llamar primero a "Detect" para obtener un faceId válido. Tenga en cuenta que este faceId no se conserva y expirará 24 horas después de la llamada de detección.
faceIds	True	string[]	Matriz de faceIds candidatos. Todos ellos se crean mediante "Detectar" y los faceIds expirarán 24 horas después de la llamada de detección. El número de faceIds está limitado a 1000.
maxNumOfCandidatesReturned		integer	Número de caras similares superiores devueltas. El intervalo válido es [1, 1000]. El valor predeterminado es 20.
mode		FindSimilarMatchMode	Modo de búsqueda facial similar. Puede ser 'matchPerson' o 'matchFace'. El valor predeterminado es 'matchPerson'.

Respuestas

Nombre	Tipo	Description
200 OK	FindSimilarResult[]	Una llamada correcta devuelve una matriz de las caras más similares representadas en faceId si el parámetro de entrada es faceIds o persistedFaceId si el parámetro de entrada es faceListId o largeFaceListId.
Other Status Codes	FaceErrorResponse	Respuesta de error inesperada. Headers x-ms-error-code: string

Seguridad

Ocp-Apim-Subscription-Key

Clave secreta de la suscripción de Azure AI Face.

Type: apiKey
In: header

AADToken

Flujo de OAuth2 de Azure Active Directory

Type: oauth2
Flow: accessCode
Authorization URL: https://api.example.com/oauth2/authorize
Token URL: https://api.example.com/oauth2/token

Scopes

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

Ejemplos

Find Similar among Face IDs

Sample Request

HTTP

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

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

Sample Response

Status code:

200

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

Definiciones

Nombre	Description
FaceError	Objeto de error. Para obtener detalles completos sobre los códigos de error y los mensajes devueltos por Face Service, consulte el siguiente vínculo: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Una respuesta que contiene los detalles del error.
FindSimilarResult	Cuerpo de la respuesta para buscar una operación facial similar.

FaceError

Objeto de error. Para obtener detalles completos sobre los códigos de error y los mensajes devueltos por Face Service, consulte el siguiente vínculo: https://aka.ms/face-error-codes-and-messages.

Nombre	Tipo	Description
code	string	Uno de los conjuntos de códigos de error definidos por el servidor.
message	string	Representación legible del error.

FaceErrorResponse

Una respuesta que contiene los detalles del error.

Nombre	Tipo	Description
error	FaceError	Objeto de error.

FindSimilarResult

Cuerpo de la respuesta para buscar una operación facial similar.

Nombre	Tipo	Description
confidence	number	Valor de confianza del candidato. Cuanto mayor sea la confianza, más similar. Intervalo entre [0,1].
faceId	string	faceId de la cara candidata cuando se encuentra por faceIds. FaceId se crea mediante "Detectar" y expirará 24 horas después de la llamada de detección.
persistedFaceId	string	persistedFaceId de la cara candidata cuando se encuentra por faceListId o largeFaceListId. persistedFaceId en la lista de caras o en la lista de caras grandes se conserva y no expirará.