Face API (Preview)

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

This connector is available in the following products and regions:

Service Class Regions
Logic Apps Standard All Logic Apps regions except the following:
     -   Azure China regions
Flow Standard All Flow regions
PowerApps Standard All PowerApps regions

Creating a connection

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

Name Type Description
API Key securestring

API Key

Site URL string

Root site url (Example: https://westus.api.cognitive.microsoft.com ).If not specified site url will be defaulted to 'https://westus.api.cognitive.microsoft.com'.

Throttling Limits

Name Calls Renewal Period
API calls per connection120060 seconds

Actions

Add a person face

Add a representative face to a person for identification.

Add face to face list

Add face to face list.

Create a face list

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

Create a person

Create a new person in a specified person group.

Create a person group

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

Detect faces

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

Find person from face

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

Get a face list

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

Get a person

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

Get a person face

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

Get a person group

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

Add a person face

Add a representative face to a person for identification.

Parameters

Name Key Required Type Description
Person Group Id
personGroupId True string

Person group

Person Id
personId True string

Target person that the face is added to.

Image Url
url True string

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

Target Face
targetFace 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
userData 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.

Parameters

Name Key Required Type Description
Image Url
url string

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

Target Face
targetFace 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
userData string

User-specified data about the target face to add for any purpose. The maximum length is 1KB.

Face List Id
faceListId True string

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

Returns

Create a face list

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

Parameters

Name Key Required Type Description
Face List Id
faceListId True string

Valid character is letter in lower case or digit or '-' or '_', maximum length is 64

Face List Name
name True string

Name of the created face list, maximum length is 128.

User Data
userData string

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

Create a person

Create a new person in a specified person group.

Parameters

Name Key Required Type Description
Person Group Id
personGroupId True string

Specifying the target person group to create the person.

Name
name True string

Display name of the target person. The maximum length is 128.

User Data
userData 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.

Parameters

Name Key Required Type Description
Person Group Id
personGroupId True string

New Person Group Id (valid characters include numbers, English letters in lower case, '-' and '_')

Name
name True string

Person group display name. The maximum length is 128.

User Data
userData string

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

Detect faces

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

Parameters

Name Key Required Type Description
Image Url
url True 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.

Parameters

Name Key Required Type Description
Face Id
faceId True string

Unique faceId of the detected face. Will expire 24 hours after detection call.

Person Group Id
personGroupId True string

Person Group Id created in Face API - Create Person Group action.

Person Id
personId True 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.

Parameters

Name Key Required Type Description
Face List Id
faceListId True string

faceListId of the target face list.

Returns

Get a person

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

Parameters

Name Key Required Type Description
Person Group Id
personGroupId True string

Specifying the person group containing the target person.

Person Id
personId True string

Specifying the target person.

Returns

Get a person face

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

Parameters

Name Key Required Type Description
Person Group Id
personGroupId True string

Specifying the person group containing the target person.

Person Id
personId True string

Specifying the target person that the face belongs to.

Persisted Face Id
persistedFaceId True 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.

Parameters

Name Key Required Type Description
Person Group Id
personGroupId True string

Target Person Group Id.

Returns

Definitions

DetectResponse

Name Path Type Description
Face Id
faceId string

Unique faceId of the detected face. Will expire 24 hours after detection call.

Top
faceRectangle.top integer

Parameters of a rectangle area for the face location on image.

Left
faceRectangle.left integer

Parameters of a rectangle area for the face location on image.

Width
faceRectangle.width integer

Parameters of a rectangle area for the face location on image.

Height
faceRectangle.height integer

Parameters of a rectangle area for the face location on image.

Left Pupil X
faceLandmarks.pupilLeft.x float

The x-coordinate of the left pupil.

Left Pupil Y
faceLandmarks.pupilLeft.y float

The y-coordinate of the left pupil.

Right Pupil X
faceLandmarks.pupilRight.x float

The x-coordinate of the right pupil.

Right Pupil Y
faceLandmarks.pupilRight.y float

The y-coordinate of the right pupil.

Nose Tip X
faceLandmarks.noseTip.x float

The x-coordinate of the nose tip.

Nose Tip Y
faceLandmarks.noseTip.y float

The y-coordinate of the nose tip.

Mouth Left X
faceLandmarks.mouthLeft.x float

The x-coordinate for the left side of the mouth.

Mouth Left Y
faceLandmarks.mouthLeft.y float

The y-coordinate for the left side of the mouth.

Mouth Right X
faceLandmarks.mouthRight.x float

The x-coordinate for the right side of the mouth.

Mouth Right Y
faceLandmarks.mouthRight.y float

The y-coordinate for the right side of the mouth.

Outer Left Eyebrow X
faceLandmarks.eyebrowLeftOuter.x float

The x-coordinate for the outer side of the left eyebrow.

Outer Left Eyebrow Y
faceLandmarks.eyebrowLeftOuter.y float

The y-coordinate for the outer side of the left eyebrow.

Inner Left Eybrow X
faceLandmarks.eyebrowLeftInner.x float

The x-coordinate for the inner side of the left eyebrow.

Inner Left Eyebrow Y
faceLandmarks.eyebrowLeftInner.y float

The y-coordinate for the inner side of the left eyebrow.

Outer Left Eye X
faceLandmarks.eyeLeftOuter.x float

The x-coordinate for the outer side of the left eye.

Outer Left Eye Y
faceLandmarks.eyeLeftOuter.y float

The y-coordinate for the outer side of the left eye.

Top of Left Eye X
faceLandmarks.eyeLeftTop.x float

The x-coordinate for the top of the left eye.

Top of Left Eye Y
faceLandmarks.eyeLeftTop.y float

The y-coordinate for the top of the left eye.

Bottom of Left Eye X
faceLandmarks.eyeLeftBottom.x float

The x-coordinate for the bottom of the left eye.

Bottom of Left Eye Y
faceLandmarks.eyeLeftBottom.y float

The y-coordinate for the bottom of the left eye.

Inner Left Eye X
faceLandmarks.eyeLeftInner.x float

The x-coordinate for the inner side of the left eye.

Inner Left Eye Y
faceLandmarks.eyeLeftInner.y float

The y-coordinate for the inner side of the left eye.

Inner Right Eybrow X
faceLandmarks.eyebrowRightInner.x float

The x-coordinate for the inner side of the right eyebrow.

Inner Right Eyebrow Y
faceLandmarks.eyebrowRightInner.y float

The y-coordinate for the inner side of the right eyebrow.

Outer Right Eyebrow X
faceLandmarks.eyebrowRightOuter.x float

The x-coordinate for the outer side of the right eyebrow.

Outer Right Eyebrow Y
faceLandmarks.eyebrowRightOuter.y float

The y-coordinate for the outer side of the right eyebrow.

Inner Right Eye X
faceLandmarks.eyeRightInner.x float

The x-coordinate for the inner side of the right eye.

Inner Right Eye Y
faceLandmarks.eyeRightInner.y float

The y-coordinate for the inner side of the right eye.

Top of Right Eye X
faceLandmarks.eyeRightTop.x float

The x-coordinate for the top of the right eye.

Top of Right Eye Y
faceLandmarks.eyeRightTop.y float

The y-coordinate for the top of the right eye.

Bottom of Right Eye X
faceLandmarks.eyeRightBottom.x float

The x-coordinate for the bottom of the right eye.

Bottom of Right Eye Y
faceLandmarks.eyeRightBottom.y float

The y-coordinate for the bottom of the right eye.

Outer Right Eye X
faceLandmarks.eyeRightOuter.x float

The x-coordinate for the outer side of the right eye.

Outer Right Eye Y
faceLandmarks.eyeRightOuter.y float

The y-coordinate for the outer side of the right eye.

Left Nose Root X
faceLandmarks.noseRootLeft.x float

The x-coordinate for left side of the nose root.

Left Nose Root Y
faceLandmarks.noseRootLeft.y float

The y-coordinate for left side of the nose root.

Right Nose Root X
faceLandmarks.noseRootRight.x float

The x-coordinate for right side of the nose root.

Right Nose Root Y
faceLandmarks.noseRootRight.y float

The y-coordinate for right side of the nose root.

Top of Left Nose Altar X
faceLandmarks.noseLeftAlarTop.x float

The x-coordinate for top of the left nose altar.

Top of Left Nose Altar Y
faceLandmarks.noseLeftAlarTop.y float

The y-coordinate for top of the left nose altar.

Top of Right Nose Altar X
faceLandmarks.noseRightAlarTop.x float

The x-coordinate for top of the right nose altar.

Top of Right Nose Altar Y
faceLandmarks.noseRightAlarTop.y float

The y-coordinate for top of the right nose altar.

Tip of Left Nose Altar Out X
faceLandmarks.noseLeftAlarOutTip.x float

The x-coordinate for tip of the left nose altar.

Tip of Left Nose Altar Out Y
faceLandmarks.noseLeftAlarOutTip.y float

The y-coordinate for tip of the left nose altar/

Tip of Right Nose Altar Out X
faceLandmarks.noseRightAlarOutTip.x float

The x-coordinate for tip of the right nose altar.

Tip of Right Nose Altar Out Y
faceLandmarks.noseRightAlarOutTip.y float

The y-coordinate for tip of the right nose altar.

Top of Upper Lip X
faceLandmarks.upperLipTop.x float

The x-coordinate for top of upper lip.

Top of Upper Lip Y
faceLandmarks.upperLipTop.y float

The y-coordinate for top of upper lip.

Bottom of Upper Lip X
faceLandmarks.upperLipBottom.x float

The x-coordinate for bottom of upper lip.

Bottom of Upper Lip Y
faceLandmarks.upperLipBottom.y float

The y-coordinate for bottom of upper lip.

Top of Under Lip X
faceLandmarks.underLipTop.x float

The x-coordinate for top of under lip.

Top of Under Lip Y
faceLandmarks.underLipTop.y float

The y-coordinate for top of under lip.

Bottom of Under Lip X
faceLandmarks.underLipBottom.x float

The x-coordinate for bottom of under lip.

Bottom of Under Lip Y
faceLandmarks.underLipBottom.y float

The y-coordinate for bottom of under lip.

Smile
faceAttributes.smile float

Intensity between [0,1].

Head Pose Pitch
faceAttributes.headPose.pitch float

Reserved field, always returns 0.

Head Pose Roll
faceAttributes.headPose.roll float

Roll of the head pose.

Head Pose Yaw
faceAttributes.headPose.yaw float

Yaw of the head pose.

Gender
faceAttributes.gender string

Male for female.

Age
faceAttributes.age float

Age of person.

Moustache
faceAttributes.facialHair.moustache float

Intensity between [0,1].

Beard
faceAttributes.facialHair.beard float

Intensity between [0,1].

Sideburns
faceAttributes.facialHair.sideburns float

Intensity between [0,1].

Glasses
faceAttributes.glasses string

Type of glasses.

AddPersonFaceResponse

Name Path Type Description
Persisted Face Id
persistedFaceId string

GetPersonGroupResponse

Name Path Type Description
Person Group Id
personGroupId string
Name
name string
userData
userData string

GetFaceListResponse

Name Path Type Description
Persisted Faces
persistedFaces array of object
Persisted Face Id
persistedFaces.persistedFaceId string

Id of the face.

User Data
persistedFaces.userData string

User-provided data attached to each face.

Face List Id
faceListId string

faceListId of the target face list.

Name
name string

Face list's display name.

User Data
userData string

User-provided data attached to the face list.

GetPersonFaceResponse

Name Path Type Description
Persisted Face Id
persistedFaceId string
userData
userData string

CreatePersonResponse

Name Path Type Description
Person Id
personId string

GetPersonResponse

Name Path Type Description
Person Id
personId string
Persisted Face Ids
persistedFaceIds array of object
Persisted Face Id
persistedFaceIds.persistedFaceId string
Name
name string
User Data
userData string

VerifyResponse

Name Path Type Description
Is Identical
isIdentical boolean

True if the two faces belong to the same person or the face belongs to the person, otherwise false.

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