Large Face List - Create

Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel.
Large face list is a list of faces, up to 1,000,000 faces, and used by Face - Find Similar.
After creation, user should use LargeFaceList Face - Add to import the faces and LargeFaceList - Train to make it ready for Face - Find Similar. No image will be stored. Only the extracted face features are stored on server until LargeFaceList - 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.
'recognitionModel' should be specified to associate with this large 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 large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. Please refer to Specify a recognition model.

Large face list quota:

  • Free-tier subscription quota: 64 large face lists.
  • S0-tier subscription quota: 1,000,000 large face lists.
PUT {Endpoint}/face/v1.0/largefacelists/{largeFaceListId}

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

largeFaceListId
path True

string

Id referencing a particular large 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 large face list example

Sample Request

PUT {Endpoint}/face/v1.0/largefacelists/sample_face_list


{
  "name": "large-face-list-name",
  "userData": "User-provided data attached to the large face list.",
  "recognitionModel": "recognition_01"
}

Sample Response

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