Person Group - Create

Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel.
A person group is the container of the uploaded person data, including face recognition features.
After creation, use PersonGroup Person - Create to add persons into the group, and then call PersonGroup - Train to get this group ready for Face - Identify.
No image will be stored. Only the person's extracted face features and userData will be stored on server until PersonGroup Person - Delete or PersonGroup - Delete is called.
'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model.

  • 'recognition_01': The default recognition model for PersonGroup - Create. All those person groups created before 2019 March are bonded with this recognition model.
  • 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'.

Person group quota:

  • Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons.
  • S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons.
  • to handle larger scale face identification problem, please consider using LargePersonGroup.
PUT {Endpoint}/face/v1.0/persongroups/{personGroupId}

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).

personGroupId
path True
  • string

Id referencing a particular person group.

Regex pattern: ^[a-z0-9-_]+$

Request Body

Name Type Description
name
  • string

User defined name, maximum length is 128.

recognitionModel

Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need.

userData
  • string

User specified data. Length should not exceed 16KB.

Responses

Name Type Description
200 OK

A successful call returns an empty response body.

Other Status Codes

Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Create new person group example

Sample Request

PUT {Endpoint}/face/v1.0/persongroups/abc
{
  "name": "group1",
  "userData": "user-provided data attached to the person group.",
  "recognitionModel": "recognition_01"
}

Sample Response

Definitions

APIError

Error information returned by the API

Error

Error body.

MetaDataContract

A combination of user defined name and user specified data and recognition model name for largePersonGroup/personGroup, and largeFaceList/faceList.

RecognitionModel

Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need.

APIError

Error information returned by the API

Name Type Description
error

Error body.

Error

Error body.

Name Type Description
code
  • string
message
  • string

MetaDataContract

A combination of user defined name and user specified data and recognition model name for largePersonGroup/personGroup, and largeFaceList/faceList.

Name Type Description
name
  • string

User defined name, maximum length is 128.

recognitionModel

Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need.

userData
  • string

User specified data. Length should not exceed 16KB.

RecognitionModel

Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need.

Name Type Description
recognition_01
  • string
recognition_02
  • string