Face Recognition Operations - Find Similar From Face List

Servicio:

Azure AI Services

Versión de la API:

v1.2-preview.1

Dado el faceId de la consulta, para buscar las caras similares de una lista de caras. Create Face List crea un elemento "faceListId".
Dependiendo de la entrada, la lista de caras similares devueltas 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 de celebridad.

El elemento "recognitionModel" asociado al faceId de consulta debe ser el mismo que el "recognitionModel" usado por la lista de caras de destino.

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

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
apiVersion	path	True	string	Versión de 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.
faceListId	True	string	Una lista de caras candidata única especificada por el usuario existente, creada en "Crear lista de caras". La lista de caras contiene un conjunto de persistedFaceIds que se conservan y nunca expirarán.
maxNumOfCandidatesReturned		integer	Número de caras superiores similares 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	Una respuesta de error inesperada. Encabezados x-ms-error-code: string

Seguridad

Ocp-Apim-Subscription-Key

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

Tipo: apiKey
En: header

AADToken

Flujo de OAuth2 de Azure Active Directory

Tipo: oauth2
Flujo: accessCode
Dirección URL de autorización: https://api.example.com/oauth2/authorize
Dirección URL del token: https://api.example.com/oauth2/token

Ámbitos

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

Ejemplos

Find Similar from FaceList

Solicitud de ejemplo

HTTP

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

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

Respuesta de muestra

status code:

200

[
  {
    "confidence": 0.8,
    "faceId": "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 vínculo siguiente: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Respuesta que contiene los detalles del error.
FindSimilarResult	Cuerpo de 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 vínculo siguiente: https://aka.ms/face-error-codes-and-messages.

Nombre	Tipo	Description
code	string	Uno de un conjunto definido por el servidor de códigos de error.
message	string	Representación legible del error.

FaceErrorResponse

Respuesta que contiene los detalles del error.

Nombre	Tipo	Description
error	FaceError	Objeto de error.

FindSimilarResult

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

Nombre	Tipo	Description
confidence	number	Valor de confianza del candidato. Mayor 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 la lista de caras grandes se conserva y no expirará.