Share via


Face API

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
Power Automate Standard All Power Automate regions
Power Apps Standard All Power Apps regions
Contact
Name Microsoft
URL Microsoft LogicApps Support
Microsoft Power Automate Support
Microsoft Power Apps Support
Connector Metadata
Publisher Microsoft
Website https://azure.microsoft.com/services/cognitive-services/face/

To use this integration, you will need a Cognitive Service resource in the Azure portal. You will get an endpoint and a key for authenticating your applications. To make a connection, provide the Account key, site URL and select Create connection. For operation costs on your connection, learn more here.

You're now ready to start using this integration.

Connecting with Microsoft Entra ID

To create connections with Microsoft Entra ID, you must add the Cognitive Services User role to your account to access. To use this connection, you must input the unique subdomain associated wih your Cognitive Services resource into the supporting operations.

Operations not supported with Microsoft Entra ID authentication

When using Microsoft Entra ID authentication only V2 actions are supported. Deprecated actions will continue to work with Access Key authentication, but will fail if used with an Microsoft Entra ID connection.

Creating a connection

The connector supports the following authentication types:

Api Key Api Key All regions Shareable
Default [DEPRECATED] This option is only for older connections without an explicit authentication type, and is only provided for backward compatibility. All regions Not shareable

Api Key

Auth ID: keyBasedAuth

Applicable: All regions

Api Key

This is shareable connection. If the power app is shared with another user, connection is shared as well. For more information, please see the Connectors overview for canvas apps - Power Apps | Microsoft Docs

Name Type Description Required
Account Key securestring Cognitive Services Account Key
Site URL string Root site url (Example: https://westus.api.cognitive.microsoft.com)

Default [DEPRECATED]

Applicable: All regions

This option is only for older connections without an explicit authentication type, and is only provided for backward compatibility.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Name Type Description Required
API Key securestring API Key True
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 connection 1200 60 seconds

Actions

Add a person face

Add a representative face to a person for identification.

Add a person face (V2)

Add a representative face to a person for identification.

Add face to face list

Add face to face list.

Add face to face list (V2)

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 face list (V2)

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 (V2)

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.

Create a person group (V2)

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.

Detect faces (V2)

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.

Find person from face (V2)

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 face list (V2)

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 (V2)

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 face (V2)

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.

Get a person group (V2)

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 a person face (V2)

Add a representative face to a person for identification.

Parameters

Name Key Required Type Description
Resource Subdomain or Region
subdomain True string

Azure subdomain or geographic region (e.g. westus)

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

Add face to face list (V2)

Add face to face list.

Parameters

Name Key Required Type Description
Resource Subdomain or Region
subdomain True string

Azure subdomain or geographic region (e.g. westus)

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 face list (V2)

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

Parameters

Name Key Required Type Description
Resource Subdomain or Region
subdomain True string

Azure subdomain or geographic region (e.g. westus)

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 (V2)

Create a new person in a specified person group.

Parameters

Name Key Required Type Description
Resource Subdomain or Region
subdomain True string

Azure subdomain or geographic region (e.g. westus)

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.

Create a person group (V2)

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

Parameters

Name Key Required Type Description
Resource Subdomain or Region
subdomain True string

Azure subdomain or geographic region (e.g. westus)

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

Detect faces (V2)

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

Parameters

Name Key Required Type Description
Resource Subdomain or Region
subdomain True string

Azure subdomain or geographic region (e.g. westus)

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

Find person from face (V2)

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

Parameters

Name Key Required Type Description
Resource Subdomain or Region
subdomain True string

Azure subdomain or geographic region (e.g. westus)

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 face list (V2)

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

Parameters

Name Key Required Type Description
Resource Subdomain or Region
subdomain True string

Azure subdomain or geographic region (e.g. westus)

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 (V2)

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

Parameters

Name Key Required Type Description
Resource Subdomain or Region
subdomain True string

Azure subdomain or geographic region (e.g. westus)

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 face (V2)

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

Parameters

Name Key Required Type Description
Resource Subdomain or Region
subdomain True string

Azure subdomain or geographic region (e.g. westus)

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

Get a person group (V2)

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

Parameters

Name Key Required Type Description
Resource Subdomain or Region
subdomain True string

Azure subdomain or geographic region (e.g. westus)

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.

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.

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.