Face - Group

Service:

Azure AI Services

API Version:

1.0-preview

Divide candidate faces into groups based on face similarity.

• The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result.
• MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts.
• Group API needs at least 2 candidate faces and 1000 at most. We suggest to try Face - Verify when you only have 2 candidate faces.
• The 'recognitionModel' associated with the query faces' faceIds should be the same.

POST {Endpoint}/face/v1.0-preview/group

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[] (uuid)	Array of candidate faceId created by Face - Detect. The maximum is 1000 faces

Responses

Name	Type	Description
200 OK	GroupResult	A successful call returns one or more groups of similar faces (rank by group size) and a messyGroup.
Other Status Codes	APIError	Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Group example

Sample request

HTTP

POST {Endpoint}/face/v1.0-preview/group


{
  "faceIds": [
    "c5c24a82-6845-4031-9d5d-978df9175426",
    "015839fb-fbd9-4f79-ace9-7675fc2f1dd9",
    "65d083d4-9447-47d1-af30-b626144bf0fb",
    "fce92aed-d578-4d2e-8114-068f8af4492e",
    "30ea1073-cc9e-4652-b1e3-d08fb7b95315",
    "be386ab3-af91-4104-9e6d-4dae4c9fddb7",
    "fbd2a038-dbff-452c-8e79-2ee81b1aa84e",
    "b64d5e15-8257-4af2-b20a-5a750f8940e7"
  ]
}

Sample response

Status code:

200

{
  "groups": [
    [
      "c5c24a82-6845-4031-9d5d-978df9175426",
      "015839fb-fbd9-4f79-ace9-7675fc2f1dd9",
      "fce92aed-d578-4d2e-8114-068f8af4492e",
      "b64d5e15-8257-4af2-b20a-5a750f8940e7"
    ],
    [
      "65d083d4-9447-47d1-af30-b626144bf0fb",
      "30ea1073-cc9e-4652-b1e3-d08fb7b95315"
    ]
  ],
  "messyGroup": [
    "be386ab3-af91-4104-9e6d-4dae4c9fddb7"
  ]
}

Definitions

Name	Description
APIError	Error information returned by the API
Error	Error body.
GroupRequest	Request body for group request.
GroupResult	An array of face groups based on face similarity.

APIError

Object

Error information returned by the API

Name	Type	Description
error	Error	Error body.

Error

Object

Error body.

Name	Type	Description
code	string
message	string

GroupRequest

Object

Request body for group request.

Name	Type	Description
faceIds	string[] (uuid)	Array of candidate faceId created by Face - Detect. The maximum is 1000 faces

GroupResult

Object

An array of face groups based on face similarity.

Name	Type	Description
groups	string[] (uuid)	A partition of the original faces based on face similarity. Groups are ranked by number of faces
messyGroup	string[] (uuid)	Face ids array of faces that cannot find any similar faces from original faces.