Face - Identify

Reference

Service:: Cognitive Services - Face

API Version:: 1.0

1-to-many identification to find the closest matches of the specific query person face from a person group or large person group.
For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in PersonGroup - Train and LargePersonGroup - Train.

Remarks:

The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces.
Each person in the person group/large person group could have more than one face, but no more than 248 faces.
Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array.
Try 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.
The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group.

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

URI Parameters

Name	In	Required	Type	Description
Endpoint	path	True	string	Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).

Request Header

Name	Required	Type	Description
Ocp-Apim-Subscription-Key	True	string

Request Body

Name	Required	Type	Description
faceIds	True	string[]	Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10].
confidenceThreshold		number	Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm).
largePersonGroupId		string	LargePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time.
maxNumOfCandidatesReturned		integer	The range of maxNumOfCandidatesReturned is between 1 and 100 (default is 1).
personGroupId		string	PersonGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time.

Responses

Name	Type	Description
200 OK	IdentifyResult[]	A successful call returns the identified candidate person(s) for each query face.
Other Status Codes	APIError	Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Identify example

Sample Request

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
}

Sample Response

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
      }
    ]
  }
]

Definitions

APIError	Error information returned by the API
Error	Error body.
IdentifyCandidate	All possible faces that may qualify.
IdentifyRequest	Request body for identify face operation.
IdentifyResult	Response body for identify face operation.

APIError

Error information returned by the API

Name	Type	Description
error	Error	Error body.

Error

Error body.

Name	Type	Description
code	string
message	string

IdentifyCandidate

All possible faces that may qualify.

Name	Type	Description
confidence	number	Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm).
personId	string	Id of candidate

IdentifyRequest

Request body for identify face operation.

Name	Type	Default Value	Description
confidenceThreshold	number		Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm).
faceIds	string[]		Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10].
largePersonGroupId	string		LargePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time.
maxNumOfCandidatesReturned	integer	1	The range of maxNumOfCandidatesReturned is between 1 and 100 (default is 1).
personGroupId	string		PersonGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time.

IdentifyResult

Response body for identify face operation.

Name	Type	Description
candidates	IdentifyCandidate[]	Identified person candidates for that face (ranked by confidence). Array size should be no larger than input maxNumOfCandidatesReturned. If no person is identified, will return an empty array.
faceId	string	FaceId of the query face