new MSCSFaceApi(key, server)
Creates an instance os MSCSFaceApi
Parameters:
| Name | Type | Description |
|---|---|---|
key |
String | Subscription key which provides access to this API. Found in your Cognitive Services accounts. |
server |
String | Server short name to use this API. Options: WUS (westus), EUS2 (eastus2), WCUS (westcentralus), WE (westeurope) and SA (southeastasia). |
- Source:
Methods
addPersonFace(personGroupId, personId, userData, image) → {Promise}
Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face and this persistedFaceId will not expire.
Note persistedFaceId is different from faceId which represents the detected face by Face - Detect.
Parameters:
| Name | Type | Description |
|---|---|---|
personGroupId |
String | Specifying the person group containing the target person. |
personId |
String | Target person that the face is added to. |
userData |
String | User-specified data about the target face to add for any purpose. The maximum length is 1KB. (optional) |
image |
String | Face image URL. Valid image size is from 1KB to 4MB. Only one face is allowed per image. |
- Source:
Returns:
A successful call returns the new persistedFaceId. A unsuccessful call returns the error.
- Type
- Promise
createPerson(personGroupId, name, userData) → {Promise}
Create a new person in a specified person group. A newly created person have no registered face, you can call Person - Add a Person Face API to add faces to the person.
Parameters:
| Name | Type | Description |
|---|---|---|
personGroupId |
String | Specifying the target person group to create the person. |
name |
String | Display name of the target person. The maximum length is 128. |
userData |
String | Optional fields for user-provided data attached to a person. Size limit is 16KB. (optional) |
- Source:
Returns:
A successful call returns a new personId created. A unsuccessful call returns the error.
- Type
- Promise
createPersonGroup(personGroupId, name, userData) → {Promise}
Create a new person group with specified personGroupId, name and user-provided userData.
Parameters:
| Name | Type | Description |
|---|---|---|
personGroupId |
String | User-provided personGroupId as a String. The valid characters include numbers, English letters in lower case, '-' and '_'. The maximum length of the personGroupId is 64. |
name |
String | Person group display name. The maximum length is 128. |
userData |
String | User-provided data attached to the person group. The size limit is 16KB. (optional) |
- Source:
Returns:
A successful call returns an empty response body. A unsuccessful call returns the error.
- Type
- Promise
deletePersonGroup(personGroupId) → {Promise}
Delete an existing person group.
Persisted face images of all people in the person group will also be deleted.
Parameters:
| Name | Type | Description |
|---|---|---|
personGroupId |
String | The personGroupId of the person group to be deleted. |
- Source:
Returns:
A successful call returns an empty response body. A unsuccessful call returns the error.
- Type
- Promise
detectFace(image) → {Promise}
Detect human faces in an image and returns face locations and faceIds of the detected faces.
Parameters:
| Name | Type | Description |
|---|---|---|
image |
String | URL of input image. |
- Source:
Returns:
A successful call returns an array of face entries ranked by face rectangle size in descending order and faceIds. An empty response indicates no faces detected. A unsuccessful call returns the error.
- Type
- Promise
getPersonGroup(personGroupId) → {Promise}
Retrieve the information of a person group, including its name and userData.
This API returns person group information only, use Person - List Persons in a Person Group instead to retrieve person information under the person group.
Parameters:
| Name | Type | Description |
|---|---|---|
personGroupId |
String | personGroupId of the target person group. |
- Source:
Returns:
A successful call returns the person group's information. A unsuccessful call returns the error.
- Type
- Promise
getPersonGroupTrainingStatus(personGroupId) → {Promise}
Retrieve the training status of a person group (completed or ongoing).
Training can be triggered by the Person Group - Train Person Group API. The training will process for a while on the server side.
Parameters:
| Name | Type | Description |
|---|---|---|
personGroupId |
String | personGroupId of target person group. |
- Source:
Returns:
A successful call returns the person group's training status. A unsuccessful call returns the error.
- Type
- Promise
identifyFace(personGroupId, faceIds, confidenceThreshold) → {Promise}
Identify unknown faces from a person group.
Parameters:
| Name | Type | Description |
|---|---|---|
personGroupId |
String | personGroupId of the target person group, created by Person Group - Create a Person Group. |
faceIds |
Array | Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between. |
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). (optional) |
- Source:
Returns:
A successful call returns the identified candidate person(s) for each query face. An empty response indicates no faces detected. A unsuccessful call returns the error.
- Type
- Promise
listPersonGroups(start, top) → {Promise}
List person groups and their information.
Parameters:
| Name | Type | Description |
|---|---|---|
start |
String | List person groups from the least personGroupId greater than the "start". It contains no more than 64 characters. Default is empty. (optional) |
top |
int | The number of person groups to list, ranging in [1, 1000]. Default is 1000. (optional) |
- Source:
Returns:
A successful call returns an array of person groups and their information (personGroupId, name and userData). A unsuccessful call returns the error.
- Type
- Promise
listPersonsInPersonGroup(personGroupId, start, top) → {Promise}
List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person).
Parameters:
| Name | Type | Description |
|---|---|---|
personGroupId |
String | personGroupId of the target person group. |
start |
String | List persons from the least personId greater than the "start". It contains no more than 64 characters. Default is empty. (optional) |
top |
int | The number of persons to list, ranging in [1, 1000]. Default is 1000. (optional) |
- Source:
Returns:
A successful call returns an array of person information that belong to the person group. A unsuccessful call returns the error.
- Type
- Promise
trainPersonGroup(personGroupId) → {Promise}
Queue a person group training task, the training task may not be started immediately.
Parameters:
| Name | Type | Description |
|---|---|---|
personGroupId |
String | Target person group to be trained. |
- Source:
Returns:
A successful call returns an empty JSON body. A unsuccessful call returns the error.
- Type
- Promise
updatePersonGroup(personGroupId, name, userData) → {Promise}
Update an existing person group's display name and userData. The properties which does not appear in request body will not be updated.
Parameters:
| Name | Type | Description |
|---|---|---|
personGroupId |
String | personGroupId of the person group to be updated. |
name |
String | Person group display name. The maximum length is 128. |
userData |
String | User-provided data attached to the person group. The size limit is 16KB. |
- Source:
Returns:
A successful call returns an empty JSON body. A unsuccessful call returns the error.
- Type
- Promise