Face API (Preview)

Face API (Preview)

Microsoft Cognitive Services Face API allows you to detect, identify, analyze, organize and tag faces in photos.

Creating a connection

To connect your account, you will need the following information:

API Key
securestring
API Key
Site URL
string
Root site url (Example: https://westus.api.cognitive.microsoft.com )
Actions

Add a person face

Add a representative face to a person for identification.

Required Parameters

Person Group Id
string
Person group
Person Id
string
Target person that the face is added to.
Image Url
string
Image must be JPEG, PNG, GIF(the first frame), or BMP

Optional Parameters

Target Face
string
A face rectangle to specify the target face to be added to a person, in the format of targetFace=left,top,width,height
User Data
string
User-specified data about the target face to add for any purpose. The maximum length is 1KB.

Returns

Add face to face list

Add face to face list.

Required Parameters

Face List Id
string
Valid character is letter in lower case or digit or '-' or '_', maximum length is 64.

Optional Parameters

Image Url
string
Image must be JPEG, PNG, GIF(the first frame), or BMP
Target Face
string
A face rectangle to specify the target face to be added to a person, in the format of targetFace=left,top,width,height
User Data
string
User-specified data about the target face to add for any purpose. The maximum length is 1KB.

Returns

Create a face list

Create an empty face list with user-specified faceListId, name and an optional userData.

Required Parameters

Face List Id
string
Valid character is letter in lower case or digit or '-' or '_', maximum length is 64
Face List Name
string
Name of the created face list, maximum length is 128.

Optional Parameters

User Data
string
Optional user defined data for the face list. Length should not exceed 16KB.

Returns

Create a person

Create a new person in a specified person group.

Required Parameters

Person Group Id
string
Specifying the target person group to create the person.
Name
string
Display name of the target person. The maximum length is 128.

Optional Parameters

User Data
string
Optional fields for user-provided data attached to a person. Size limit is 16KB.

Returns

Create a person group

Create a new person group with specified personGroupId, name and user-provided userData.

Required Parameters

Person Group Id
string
New Person Group Id (valid characters include numbers, English letters in lower case, '-' and '_')
Name
string
Person group display name. The maximum length is 128.

Optional Parameters

User Data
string
User-provided data attached to the person group. The size limit is 16KB.

Returns

Detect faces

Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.

Required Parameters

Image Url
string
Image must be JPEG, PNG, GIF(the first frame), or BMP

Returns

Find person from face

Verify whether two faces belong to a same person or whether one face belongs to a person.

Required Parameters

Face Id
string
Unique faceId of the detected face. Will expire 24 hours after detection call.
Person Group Id
string
Person Group Id created in Face API - Create Person Group action.
Person Id
string
Person Id created in Face API - Create Person action.

Returns

Get a face list

Retrieve a face list's information, including faceListId, name, userData and faces in the face list.

Required Parameters

Face List Id
string
faceListId of the target face list.

Returns

Get a person

Retrieve a person's information, including registered persisted faces, name and userData.

Required Parameters

Person Group Id
string
Specifying the person group containing the target person.
Person Id
string
Specifying the target person.

Returns

Get a person face

Retrieve information about a persisted face specified by persistedFaceId, personId and its belonging personGroupId.

Required Parameters

Person Group Id
string
Specifying the person group containing the target person.
Person Id
string
Specifying the target person that the face belongs to.
Persisted Face Id
string
The persistedFaceId of the target persisted face of the person.

Returns

Get a person group

Retrieve the information of a person group, including its name and userData.

Required Parameters

Person Group Id
string
Target Person Group Id.

Returns

Definitions

DetectResponse

Age
float
Age of person.
Beard
float
Intensity between [0,1].
Bottom of Left Eye X
float
The x-coordinate for the bottom of the left eye.
Bottom of Left Eye Y
float
The y-coordinate for the bottom of the left eye.
Bottom of Right Eye X
float
The x-coordinate for the bottom of the right eye.
Bottom of Right Eye Y
float
The y-coordinate for the bottom of the right eye.
Bottom of Under Lip X
float
The x-coordinate for bottom of under lip.
Bottom of Under Lip Y
float
The y-coordinate for bottom of under lip.
Bottom of Upper Lip X
float
The x-coordinate for bottom of upper lip.
Bottom of Upper Lip Y
float
The y-coordinate for bottom of upper lip.
Face Id
string
Unique faceId of the detected face. Will expire 24 hours after detection call.
Gender
string
Male for female.
Glasses
string
Type of glasses.
Head Pose Pitch
float
Reserved field, always returns 0.
Head Pose Roll
float
Roll of the head pose.
Head Pose Yaw
float
Yaw of the head pose.
Height
integer
Parameters of a rectangle area for the face location on image.
Inner Left Eybrow X
float
The x-coordinate for the inner side of the left eyebrow.
Inner Left Eye X
float
The x-coordinate for the inner side of the left eye.
Inner Left Eye Y
float
The y-coordinate for the inner side of the left eye.
Inner Left Eyebrow Y
float
The y-coordinate for the inner side of the left eyebrow.
Inner Right Eybrow X
float
The x-coordinate for the inner side of the right eyebrow.
Inner Right Eye X
float
The x-coordinate for the inner side of the right eye.
Inner Right Eye Y
float
The y-coordinate for the inner side of the right eye.
Inner Right Eyebrow Y
float
The y-coordinate for the inner side of the right eyebrow.
Left
integer
Parameters of a rectangle area for the face location on image.
Left Nose Root X
float
The x-coordinate for left side of the nose root.
Left Nose Root Y
float
The y-coordinate for left side of the nose root.
Left Pupil X
float
The x-coordinate of the left pupil.
Left Pupil Y
float
The y-coordinate of the left pupil.
Moustache
float
Intensity between [0,1].
Mouth Left X
float
The x-coordinate for the left side of the mouth.
Mouth Left Y
float
The y-coordinate for the left side of the mouth.
Mouth Right X
float
The x-coordinate for the right side of the mouth.
Mouth Right Y
float
The y-coordinate for the right side of the mouth.
Nose Tip X
float
The x-coordinate of the nose tip.
Nose Tip Y
float
The y-coordinate of the nose tip.
Outer Left Eye X
float
The x-coordinate for the outer side of the left eye.
Outer Left Eye Y
float
The y-coordinate for the outer side of the left eye.
Outer Left Eyebrow X
float
The x-coordinate for the outer side of the left eyebrow.
Outer Left Eyebrow Y
float
The y-coordinate for the outer side of the left eyebrow.
Outer Right Eye X
float
The x-coordinate for the outer side of the right eye.
Outer Right Eye Y
float
The y-coordinate for the outer side of the right eye.
Outer Right Eyebrow X
float
The x-coordinate for the outer side of the right eyebrow.
Outer Right Eyebrow Y
float
The y-coordinate for the outer side of the right eyebrow.
Right Nose Root X
float
The x-coordinate for right side of the nose root.
Right Nose Root Y
float
The y-coordinate for right side of the nose root.
Right Pupil X
float
The x-coordinate of the right pupil.
Right Pupil Y
float
The y-coordinate of the right pupil.
Sideburns
float
Intensity between [0,1].
Smile
float
Intensity between [0,1].
Tip of Left Nose Altar Out X
float
The x-coordinate for tip of the left nose altar.
Tip of Left Nose Altar Out Y
float
The y-coordinate for tip of the left nose altar/
Tip of Right Nose Altar Out X
float
The x-coordinate for tip of the right nose altar.
Tip of Right Nose Altar Out Y
float
The y-coordinate for tip of the right nose altar.
Top
integer
Parameters of a rectangle area for the face location on image.
Top of Left Eye X
float
The x-coordinate for the top of the left eye.
Top of Left Eye Y
float
The y-coordinate for the top of the left eye.
Top of Left Nose Altar X
float
The x-coordinate for top of the left nose altar.
Top of Left Nose Altar Y
float
The y-coordinate for top of the left nose altar.
Top of Right Eye X
float
The x-coordinate for the top of the right eye.
Top of Right Eye Y
float
The y-coordinate for the top of the right eye.
Top of Right Nose Altar X
float
The x-coordinate for top of the right nose altar.
Top of Right Nose Altar Y
float
The y-coordinate for top of the right nose altar.
Top of Under Lip X
float
The x-coordinate for top of under lip.
Top of Under Lip Y
float
The y-coordinate for top of under lip.
Top of Upper Lip X
float
The x-coordinate for top of upper lip.
Top of Upper Lip Y
float
The y-coordinate for top of upper lip.
Width
integer
Parameters of a rectangle area for the face location on image.

AddPersonFaceResponse

Persisted Face Id
string

GetPersonGroupResponse

Name
string
Person Group Id
string
userData
string

GetFaceListResponse

Face List Id
string
faceListId of the target face list.
Name
string
Face list's display name.
Persisted Face Id
string
Id of the face.
Persisted Faces
array of object
User Data
string
User-provided data attached to each face.
User Data
string
User-provided data attached to the face list.

GetPersonFaceResponse

Persisted Face Id
string
userData
string

CreatePersonResponse

Person Id
string

GetPersonResponse

Name
string
Persisted Face Ids
array of string
Person Id
string
User Data
string

VerifyResponse

Confidence
float
A number indicates the similarity confidence of whether two faces belong to the same person, or whether the face belongs to the person.
Is Identical
boolean
True if the two faces belong to the same person or the face belongs to the person, otherwise false.

Limits

NameCallsRenewal Period
API calls per connection10060 seconds