Face List - Create
Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription.
Face list is a list of faces, up to 1,000 faces, and used by Face - Find Similar.
After creation, user should use FaceList - Add Face to import the faces. No image will be stored. Only the extracted face features are stored on server until FaceList - Delete is called.
Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use PersonGroup / LargePersonGroup and Face - Identify.
Please consider LargeFaceList when the face number is large. It can support up to 1,000,000 faces.
'recognitionModel' should be specified to associate with this face list. 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 face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model.
Please Refer to Specify a face recognition model.
PUT {Endpoint}/face/v1.0/facelists/{faceListId}
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). |
face
|
path | True |
string |
Id referencing a particular face list. Regex pattern: |
Request Header
Name | Required | Type | Description |
---|---|---|---|
Ocp-Apim-Subscription-Key | True |
string |
Request Body
Name | Required | Type | Description |
---|---|---|---|
name | True |
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 face list example
Sample Request
PUT {Endpoint}/face/v1.0/facelists/sample_face_list
{
"name": "sample_list",
"userData": "User-provided data attached to the face list.",
"recognitionModel": "recognition_01"
}
Sample Response
Definitions
Name | Description |
---|---|
APIError |
Error information returned by the API |
Error |
Error body. |
Meta |
A combination of user defined name and user specified data and recognition model name for largePersonGroup/personGroup, and largeFaceList/faceList. |
Recognition |
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 | Default Value | Description |
---|---|---|---|
name |
string |
User defined name, maximum length is 128. |
|
recognitionModel | recognition_01 |
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 |
|
recognition_03 |
string |
|
recognition_04 |
string |