Face - Identify

Servicio:

Azure AI Services

Versión de la API:

1.0

Identificación de 1 a varios para encontrar las coincidencias más cercanas de la cara de la persona de la consulta específica a partir de un grupo de personas o grupo de personas de gran tamaño.
Para cada cara de la matriz faceIds, Face Identify calculará similitudes entre la cara de consulta y todas las caras del grupo de personas (dada por personGroupId) o grupo de personas grandes (dada por largePersonGroupId) y devolverá las personas candidatas para esa cara clasificadas por confianza de similitud. El grupo de personas o grupo de personas grandes debe entrenarse para que esté listo para la identificación. Consulte más información en PersonGroup- Train and LargePersonGroup - Train.

Observaciones:

• El algoritmo permite identificar más de una cara de forma independiente en la misma solicitud, pero no más de 10 caras.
• Cada persona del grupo de personas o grupo de personas grandes podría tener más de una cara, pero no más de 248 caras.
• Una mayor calidad de imagen facial significa una mejor precisión de identificación. Tenga en cuenta las caras de alta calidad: el tamaño frontal, claro y facial es de 200 x 200 píxeles (100 píxeles entre los ojos) o más grandes.
• El número de candidatos devueltos está restringido por maxNumOfCandidatesReturned y confidenceThreshold. Si no se identifica a ninguna persona, los candidatos devueltos serán una matriz vacía.
• Pruebe Face - Find Similar when you need to find similar faces from a face list/large face list instead of a person group/large person group.
• Los faceIds "recognitionModel" asociados a las caras de consulta deben ser los mismos que el "recognitionModel" usado por el grupo de personas de destino o el grupo de personas grandes.

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

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
faceIds	True	string[] (uuid)	Matriz de faceIds de caras de consulta, creadas por Face - Detect. Cada una de las caras se identifica de forma independiente. El número válido de faceIds está entre [1, 10].
confidenceThreshold		number minimum: 0 maximum: 1	Umbral de confianza de identificación, usado para juzgar si una cara pertenece a una persona. El intervalo de confianzaThreshold es [0, 1] (valor predeterminado especificado por el algoritmo).
largePersonGroupId		string maxLength: 64 pattern: ^[a-z0-9-_]+$	LargePersonGroupId del grupo de personas grandes de destino, creado por LargePersonGroup - Create. El parámetro personGroupId y largePersonGroupId no se deben proporcionar al mismo tiempo.
maxNumOfCandidatesReturned		integer minimum: 1 maximum: 100	El intervalo de maxNumOfCandidatesReturned está comprendido entre 1 y 100 (el valor predeterminado es 1).
personGroupId		string maxLength: 64 pattern: ^[a-z0-9-_]+$	PersonGroupId del grupo de personas de destino, creado por PersonGroup - Create. El parámetro personGroupId y largePersonGroupId no se deben proporcionar al mismo tiempo.

Respuestas

Nombre	Tipo	Description
200 OK	IdentifyResult[]	Una llamada correcta devuelve las personas candidatas identificadas para cada cara de consulta.
Other Status Codes	APIError	Respuesta de error.

Seguridad

Ocp-Apim-Subscription-Key

Tipo: apiKey
En: header

Ejemplos

Identify example

Solicitud de ejemplo

HTTP

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


{
  "largePersonGroupId": "sample_group",
  "faceIds": [
    "c5c24a82-6845-4031-9d5d-978df9175426",
    "65d083d4-9447-47d1-af30-b626144bf0fb"
  ],
  "maxNumOfCandidatesReturned": 1,
  "confidenceThreshold": 0.5
}

Respuesta de muestra

status code:

200

[
  {
    "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
    "candidates": [
      {
        "personId": "25985303-c537-4467-b41d-bdb45cd95ca1",
        "confidence": 0.92
      }
    ]
  },
  {
    "faceId": "65d083d4-9447-47d1-af30-b626144bf0fb",
    "candidates": [
      {
        "personId": "2ae4935b-9659-44c3-977f-61fac20d0538",
        "confidence": 0.89
      }
    ]
  }
]

Definiciones

Nombre	Description
APIError	Información de error devuelta por la API
Error	Cuerpo del error.
IdentifyCandidate	Todas las caras posibles que puedan calificar.
IdentifyRequest	Cuerpo de la solicitud para identificar la operación facial.
IdentifyResult	Cuerpo de respuesta para identificar la operación facial.

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

IdentifyCandidate

Object

Todas las caras posibles que puedan calificar.

Nombre	Tipo	Description
confidence	number minimum: 0 maximum: 1	Umbral de confianza de identificación, usado para juzgar si una cara pertenece a una persona. El intervalo de confianzaThreshold es [0, 1] (valor predeterminado especificado por el algoritmo).
personId	string (uuid)	Id. de candidato

IdentifyRequest

Object

Cuerpo de la solicitud para identificar la operación facial.

Nombre	Tipo	Valor predeterminado	Description
confidenceThreshold	number minimum: 0 maximum: 1		Umbral de confianza de identificación, usado para juzgar si una cara pertenece a una persona. El intervalo de confianzaThreshold es [0, 1] (valor predeterminado especificado por el algoritmo).
faceIds	string[] (uuid)		Matriz de faceIds de caras de consulta, creadas por Face - Detect. Cada una de las caras se identifica de forma independiente. El número válido de faceIds está entre [1, 10].
largePersonGroupId	string maxLength: 64 pattern: ^[a-z0-9-_]+$		LargePersonGroupId del grupo de personas grandes de destino, creado por LargePersonGroup - Create. El parámetro personGroupId y largePersonGroupId no se deben proporcionar al mismo tiempo.
maxNumOfCandidatesReturned	integer minimum: 1 maximum: 100	1	El intervalo de maxNumOfCandidatesReturned está comprendido entre 1 y 100 (el valor predeterminado es 1).
personGroupId	string maxLength: 64 pattern: ^[a-z0-9-_]+$		PersonGroupId del grupo de personas de destino, creado por PersonGroup - Create. El parámetro personGroupId y largePersonGroupId no se deben proporcionar al mismo tiempo.

IdentifyResult

Object

Cuerpo de respuesta para identificar la operación facial.

Nombre	Tipo	Description
candidates	IdentifyCandidate[]	Se han identificado candidatos para esa cara (clasificadas por confianza). El tamaño de la matriz no debe ser mayor que la entrada maxNumOfCandidatesReturned. Si no se identifica ninguna persona, devolverá una matriz vacía.
faceId	string (uuid)	FaceId de la cara de consulta