Face - Find Similar

Servicio:

Azure AI Services

Versión de la API:

1.0

Dado el faceId de la consulta, para buscar las caras similares de una matriz faceId, una lista de caras o una lista de caras grande. La matriz faceId contiene las caras creadas por Face - Detect With Url o Face - Detect With Stream, que expirará en el momento especificado por faceIdTimeToLive después de la creación. Un elemento "faceListId" se crea mediante FaceList: crear que contenga persistedFaceIds que no expirarán. Y LargeFaceListId crea un "largeFaceList" y crea que contiene persistedFaceIds que tampoco expirarán. 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 la consulta debe ser el mismo que el "recognitionModel" usado por la matriz faceId de destino, la lista de caras o la lista de caras grandes.

POST {Endpoint}/face/v1.0/findsimilars

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
Endpoint	path	True	string	Puntos de conexión de Cognitive Services admitidos (protocolo y nombre de host, por ejemplo: https://westus.api.cognitive.microsoft.com).

Encabezado de la solicitud

Nombre	Requerido	Tipo	Description
Ocp-Apim-Subscription-Key	True	string

Cuerpo de la solicitud

Nombre	Requerido	Tipo	Description
faceId	True	string (uuid)	FaceId de la cara de consulta. El usuario debe llamar a Face: detecte primero para obtener un faceId válido. Tenga en cuenta que este faceId no se conserva y expirará en el momento especificado por faceIdTimeToLive después de la llamada de detección.
faceIds		string[] (uuid)	Matriz de faceIds candidatas. Todos ellos se crean mediante Face- Detect y faceIds expirarán en el momento especificado por faceIdTimeToLive después de la llamada de detección. El número de faceIds está limitado a 1000. El parámetro faceListId, largeFaceListId y faceIds no se deben proporcionar al mismo tiempo.
faceListId		string maxLength: 64 pattern: ^[a-z0-9-_]+$	Una lista de caras candidatas únicas especificada por el usuario, creada en Lista de caras: crear una lista de caras. La lista de caras contiene un conjunto de persistedFaceIds que se conservan y nunca expirarán. El parámetro faceListId, largeFaceListId y faceIds no se deben proporcionar al mismo tiempo.
largeFaceListId		string maxLength: 64 pattern: ^[a-z0-9-_]+$	Una lista de caras grandes candidatas únicas especificada por el usuario, creada en LargeFaceList - Create. La lista de caras grandes contiene un conjunto de persistedFaceIds que se conservan y nunca expirarán. El parámetro faceListId, largeFaceListId y faceIds no se deben proporcionar al mismo tiempo.
maxNumOfCandidatesReturned		integer minimum: 1 maximum: 1000	Número de caras superiores similares devueltas. El intervalo válido es [1, 1000].
mode		FindSimilarMatchMode	Modo de búsqueda facial similar. Puede ser "matchPerson" o "matchFace".

Respuestas

Nombre	Tipo	Description
200 OK	SimilarFace[]	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.
Other Status Codes	APIError	Respuesta de error.

Seguridad

Ocp-Apim-Subscription-Key

Tipo: apiKey
En: header

Ejemplos

Find similar results example

Solicitud de ejemplo

HTTP

POST {Endpoint}/face/v1.0/findsimilars


{
  "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
  "largeFaceListId": "sample_list",
  "maxNumOfCandidatesReturned": 1,
  "mode": "matchPerson"
}

Respuesta de muestra

status code:

200

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

Definiciones

Nombre	Description
APIError	Información de error devuelta por la API
Error	Cuerpo del error.
FindSimilarMatchMode	Modo de búsqueda facial similar. Puede ser "matchPerson" o "matchFace".
FindSimilarRequest	Cuerpo de la solicitud para buscar una operación similar.
SimilarFace	Cuerpo de respuesta para buscar una operación facial similar.

APIError

Object

Información de error devuelta por la API

Nombre	Tipo	Description
error	Error	Cuerpo del error.

Error

Object

Cuerpo del error.

Nombre	Tipo	Description
code	string
message	string

FindSimilarMatchMode

Enumeración

Modo de búsqueda facial similar. Puede ser "matchPerson" o "matchFace".

Valor	Description
matchFace
matchPerson

FindSimilarRequest

Object

Cuerpo de la solicitud para buscar una operación similar.

Nombre	Tipo	Valor predeterminado	Description
faceId	string (uuid)		FaceId de la cara de consulta. El usuario debe llamar a Face: detecte primero para obtener un faceId válido. Tenga en cuenta que este faceId no se conserva y expirará en el momento especificado por faceIdTimeToLive después de la llamada de detección.
faceIds	string[] (uuid)		Matriz de faceIds candidatas. Todos ellos se crean mediante Face- Detect y faceIds expirarán en el momento especificado por faceIdTimeToLive después de la llamada de detección. El número de faceIds está limitado a 1000. El parámetro faceListId, largeFaceListId y faceIds no se deben proporcionar al mismo tiempo.
faceListId	string maxLength: 64 pattern: ^[a-z0-9-_]+$		Una lista de caras candidatas únicas especificada por el usuario, creada en Lista de caras: crear una lista de caras. La lista de caras contiene un conjunto de persistedFaceIds que se conservan y nunca expirarán. El parámetro faceListId, largeFaceListId y faceIds no se deben proporcionar al mismo tiempo.
largeFaceListId	string maxLength: 64 pattern: ^[a-z0-9-_]+$		Una lista de caras grandes candidatas únicas especificada por el usuario, creada en LargeFaceList - Create. La lista de caras grandes contiene un conjunto de persistedFaceIds que se conservan y nunca expirarán. El parámetro faceListId, largeFaceListId y faceIds no se deben proporcionar al mismo tiempo.
maxNumOfCandidatesReturned	integer minimum: 1 maximum: 1000	20	Número de caras superiores similares devueltas. El intervalo válido es [1, 1000].
mode	FindSimilarMatchMode	matchPerson	Modo de búsqueda facial similar. Puede ser "matchPerson" o "matchFace".

SimilarFace

Object

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

Nombre	Tipo	Description
confidence	number minimum: 0 maximum: 1	Confianza de similitud de la cara candidata. Mayor confianza, más similar. Intervalo entre [0,1].
faceId	string (uuid)	FaceId de la cara candidata cuando se encuentra por faceIds. FaceId se crea mediante Face: detecte y expirará en el momento especificado por faceIdTimeToLive después de la llamada de detección.
persistedFaceId	string (uuid)	PersistedFaceId de la cara candidata cuando se encuentra por faceListId. persistedFaceId en la lista de caras se conserva y no expirará. Como se muestra en la siguiente respuesta