Face List - Get

Service:

Azure AI Services

API Version:

1.0

Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list.

GET {Endpoint}/face/v1.0/facelists/{faceListId}

With optional parameters:

GET {Endpoint}/face/v1.0/facelists/{faceListId}?returnRecognitionModel={returnRecognitionModel}

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).
faceListId	path	True	string maxLength: 64 pattern: ^[a-z0-9-_]+$	Id referencing a particular face list.
returnRecognitionModel	query		boolean	A value indicating whether the operation should return 'recognitionModel' in response.

Request Header

Name	Required	Type	Description
Ocp-Apim-Subscription-Key	True	string

Responses

Name	Type	Description
200 OK	FaceList	A successful call returns the face list's information.
Other Status Codes	APIError	Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Get Face list example

Sample request

HTTP

GET {Endpoint}/face/v1.0/facelists/sample_face_list?returnRecognitionModel=True

Sample response

Status code:

200

{
  "faceListId": "sample_list",
  "name": "list1",
  "userData": "User-provided data attached to the face list.",
  "recognitionModel": "recognition_01",
  "persistedFaces": [
    {
      "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBD",
      "userData": "User-provided data attached to the face."
    }
  ]
}

Definitions

Name	Description
APIError	Error information returned by the API
Error	Error body.
FaceList	Face list object.
PersistedFace	PersonFace object.
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

Object

Error information returned by the API

Name	Type	Description
error	Error	Error body.

Error

Object

Error body.

Name	Type	Description
code	string
message	string

FaceList

Object

Face list object.

Name	Type	Default value	Description
faceListId	string maxLength: 64 pattern: ^[a-z0-9-_]+$		FaceListId of the target face list.
name	string minLength: 1 maxLength: 128		User defined name, maximum length is 128.
persistedFaces	PersistedFace[]		Persisted faces within the face list.
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 maxLength: 16384		User specified data. Length should not exceed 16KB.

PersistedFace

Object

PersonFace object.

Name	Type	Description
persistedFaceId	string (uuid)	The persistedFaceId of the target face, which is persisted and will not expire. Different from faceId created by Face - Detect and will expire in at the time specified by faceIdTimeToLive after the detection call.
userData	string maxLength: 1024	User-provided data attached to the face. The size limit is 1KB.

RecognitionModel

Enumeration

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.

Value	Description
recognition_01
recognition_02
recognition_03
recognition_04