Face - Identify

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 Body

Name Required Type 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 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].

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 5 (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

A successful call returns the identified candidate person(s) for each query face.

Other Status Codes

Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Identify example

Sample Request

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

[
  {
    "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 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 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

The range of maxNumOfCandidatesReturned is between 1 and 5 (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

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