Person Group Operations - Get Person Groups
List Person Groups' personGroupId, name, userData and recognitionModel.
Person Groups are stored in alphabetical order of personGroupId.
-
- "start" parameter (string, optional) specifies an ID value from which returned entries will have larger IDs based on string comparison. Setting "start" to an empty value indicates that entries should be returned starting from the first item.
- "top" parameter (int, optional) determines the maximum number of entries to be returned, with a limit of up to 1000 entries per call. To retrieve additional entries beyond this limit, specify "start" with the personId of the last entry returned in the current call.
Tip
- For example, there are total 5 items with their IDs: "itemId1", ..., "itemId5".
- "start=&top=" will return all 5 items.
- "start=&top=2" will return "itemId1", "itemId2".
- "start=itemId2&top=3" will return "itemId3", "itemId4", "itemId5".
GET {endpoint}/face/{apiVersion}/persongroups
GET {endpoint}/face/{apiVersion}/persongroups?start={start}&top={top}&returnRecognitionModel={returnRecognitionModel}
URI Parameters
Name | In | Required | Type | Description |
---|---|---|---|---|
api
|
path | True |
string |
API Version |
endpoint
|
path | True |
string uri |
Supported Cognitive Services endpoints (protocol and hostname, for example: https://{resource-name}.cognitiveservices.azure.com). |
return
|
query |
boolean |
Return 'recognitionModel' or not. The default value is false. |
|
start
|
query |
string |
List resources greater than the "start". It contains no more than 64 characters. Default is empty. |
|
top
|
query |
integer int32 |
The number of items to list, ranging in [1, 1000]. Default is 1000. |
Responses
Name | Type | Description |
---|---|---|
200 OK |
A successful call returns an array of Person Groups and their information (personGroupId, name and userData). |
|
Other Status Codes |
An unexpected error response. Headers x-ms-error-code: string |
Security
Ocp-Apim-Subscription-Key
The secret key for your Azure AI Face subscription.
Type:
apiKey
In:
header
AADToken
The Azure Active Directory OAuth2 Flow
Type:
oauth2
Flow:
accessCode
Authorization URL:
https://api.example.com/oauth2/authorize
Token URL:
https://api.example.com/oauth2/token
Scopes
Name | Description |
---|---|
https://cognitiveservices.azure.com/.default |
Examples
Get PersonGroups
Sample request
GET {endpoint}/face/v1.2-preview.1/persongroups?start=00000000-0000-0000-0000-000000000000&top=20&returnRecognitionModel=True
Sample response
[
{
"name": "your_person_group_name",
"userData": "your_user_data",
"recognitionModel": "recognition_01",
"personGroupId": "your_person_group_id"
}
]
Definitions
Name | Description |
---|---|
Face |
The error object. For comprehensive details on error codes and messages returned by the Face Service, please refer to the following link: https://aka.ms/face-error-codes-and-messages. |
Face |
A response containing error details. |
Person |
The container of the uploaded person data, including face recognition feature, and up to 10,000 persons. To handle larger scale face identification problem, please consider using Large Person Group. |
Recognition |
The recognition model for the face. |
FaceError
The error object. For comprehensive details on error codes and messages returned by the Face Service, please refer to the following link: https://aka.ms/face-error-codes-and-messages.
Name | Type | Description |
---|---|---|
code |
string |
One of a server-defined set of error codes. |
message |
string |
A human-readable representation of the error. |
FaceErrorResponse
A response containing error details.
Name | Type | Description |
---|---|---|
error |
The error object. |
PersonGroup
The container of the uploaded person data, including face recognition feature, and up to 10,000 persons. To handle larger scale face identification problem, please consider using Large Person Group.
Name | Type | Description |
---|---|---|
name |
string |
User defined name, maximum length is 128. |
personGroupId |
string |
ID of the container. |
recognitionModel |
Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds. |
|
userData |
string |
Optional user defined data. Length should not exceed 16K. |
RecognitionModel
The recognition model for the face.
Name | Type | Description |
---|---|---|
recognition_01 |
string |
The default recognition model for "Detect". All those faceIds created before 2019 March are bonded with this recognition model. |
recognition_02 |
string |
Recognition model released in 2019 March. |
recognition_03 |
string |
Recognition model released in 2020 May. |
recognition_04 |
string |
Recognition model released in 2021 February. It's recommended to use this recognition model for better recognition accuracy. |