Face List - Create

Reference

Service:: Cognitive Services - Face

API Version:: 1.0

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

Name	In	Required	Type	Description
Endpoint	path	True	string	Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).
faceListId	path	True	string	Id referencing a particular face list. Regex pattern: `^[a-z0-9-_]+$`

Endpoint

path

True

string

Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).

faceListId

path

True

string

Id referencing a particular face list.

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

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		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	APIError	Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Create new face list example

Sample Request

HTTP

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

Status code:: 200

Definitions

Name	Description
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	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	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