Face List - Add Face From Stream

Service:

Azure AI Services

API Version:

1.0-preview

Add a face to a specified face list, up to 1,000 faces.
To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until FaceList - Delete Face or FaceList - Delete is called.
Note persistedFaceId is different from faceId generated by Face - Detect.

• Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
• JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB.
• "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from Face - Detect, there’s no guarantee to detect and add the face successfully.
• Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures.
• Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel.
• The minimum detectable face size is 36x36 pixels in an image no larger than 1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels will need a proportionally larger minimum face size.
• Different 'detectionModel' values can be provided. To use and compare different detection models, please refer to How to specify a detection model.

POST {Endpoint}/face/v1.0-preview/facelists/{faceListId}/persistedfaces

With optional parameters:

POST {Endpoint}/face/v1.0-preview/facelists/{faceListId}/persistedfaces?overload=stream&userData={userData}&targetFace={targetFace}&detectionModel={detectionModel}

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.
detectionModel	query		DetectionModel	Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when performing Face - Detect or (Large)FaceList - Add Face or (Large)PersonGroup - Add Face. The default value is 'detection_01', if another model is needed, please explicitly specify it.
targetFace	query		integer[]	A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image.
userData	query		string maxLength: 1024	User-specified data about the face for any purpose. The maximum length is 1KB.

Request Header

Media Types: "application/octet-stream"

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

Request Body

Media Types: "application/octet-stream"

Name	Type	Description
Image	object (file)	An image stream.

Responses

Name	Type	Description
200 OK	PersistedFace	A successful call returns a new persistedFaceId.
Other Status Codes	APIError	Error response.

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

Examples

Add face to face list from stream example

Sample request

HTTP

POST {Endpoint}/face/v1.0-preview/facelists/sample_face_list/persistedfaces?overload=stream&userData={Customized user data}&targetFace=10,10,100,100&detectionModel=detection_01


"{Image stream in base 64 encoded format}"

Sample response

Status code:

200

{
  "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA"
}

Definitions

Name	Description
APIError	Error information returned by the API
DetectionModel	Detection model used when extracting the face.
Error	Error body.
PersistedFace	PersonFace object.

APIError

Object

Error information returned by the API

Name	Type	Description
error	Error	Error body.

DetectionModel

Enumeration

Detection model used when extracting the face.

Value	Description
detection_01
detection_02
detection_03
detection_preview_1904
ir_detection_01
expression_01

Error

Object

Error body.

Name	Type	Description
code	string
message	string

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.