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.
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.
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.
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 |
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) |
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'. |
Name | Calls | Renewal Period |
---|---|---|
API calls per connection | 1200 | 60 seconds |
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 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 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.
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.
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 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 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 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
- Body
- CreatePersonResponse
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
- Body
- CreatePersonResponse
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 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 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
- Items
- DetectResponse
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
- Items
- DetectResponse
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
- Body
- VerifyResponse
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
- Body
- VerifyResponse
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
- Body
- GetFaceListResponse
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
- Body
- GetFaceListResponse
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
- Body
- GetPersonResponse
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
- Body
- GetPersonResponse
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
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
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
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
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. |
Name | Path | Type | Description |
---|---|---|---|
Persisted Face Id
|
persistedFaceId | string |
Name | Path | Type | Description |
---|---|---|---|
Person Group Id
|
personGroupId | string | |
Name
|
name | string | |
userData
|
userData | string |
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. |
Name | Path | Type | Description |
---|---|---|---|
Persisted Face Id
|
persistedFaceId | string | |
userData
|
userData | string |
Name | Path | Type | Description |
---|---|---|---|
Person Id
|
personId | string |
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 |
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. |