Connectors Reference
Microsoft Cognitive Services Face API allows you to detect, identify, analyze, organize and tag faces in photos.
|
Status: Preview |
Tier: Standard |
Version: 1.0.0 |
|
Name |
Summary |
|
|
|
|
|
|
|
Get a face list |
|
|
CreateFaceList (string faceListId, CreateFaceListParameterBody body) |
Create a face list |
|
Detect faces |
|
|
Add a person face |
|
|
Add face to face list |
|
|
Get a person group |
|
|
CreatePersonGroup (string personGroupId, CreatePersonGroupParameterBody body) |
Create a person group |
|
Find person from face |
|
|
GetPersonFace (string personGroupId, string personId, string persistedFaceId) |
Get a person face |
|
|
|
|
CreatePerson (string personGroupId, CreatePersonParameterBody body) |
Create a person |
|
Get a person |
|
Name |
Summary |
|
Name |
Summary |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Summary:
Description:
Syntax:
FaceAPI.GetFaceListInternal ()
Returns:
Type:array of (GetFaceListInternalResponseItem)
Summary:
Description:
Syntax:
FaceAPI.GetPersonGroupsInternal ()
Returns:
Type:array of (GetPersonGroupsInternalResponseItem)
Summary: Get a face list
Description: Retrieve a face list's information, including faceListId, name, userData and faces in the face list.
Syntax:
FaceAPI.GetFaceList (string faceListId)
Parameters:
|
Name |
Type |
Summary |
Required |
Related Action |
|
faceListId |
string (Face List Id) |
faceListId of the target face list. |
True |
Returns:
Type:GetFaceListResponse
Summary: Create a face list
Description: Create an empty face list with user-specified faceListId, name and an optional userData.
Syntax:
FaceAPI.CreateFaceList (string faceListId, CreateFaceListParameterBody body)
Parameters:
|
Name |
Type |
Summary |
Required |
Related Action |
|
faceListId |
string (Face List Id) |
Valid character is letter in lower case or digit or '-' or '_', maximum length is 64 |
True |
|
|
body |
|
|
True |
Returns:
Summary: Detect faces
Description: Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.
Syntax:
FaceAPI.Detect ([internal][Optional]string returnFaceId, DetectParameterBody body, [internal][Optional]string returnFaceAttributes, [internal][Optional]string returnFaceLandmarks)
Parameters:
|
Name |
Type |
Summary |
Required |
Related Action |
|
returnFaceId |
string (returnFaceIds) |
|
False |
|
|
body |
|
|
True |
|
|
returnFaceAttributes |
string
|
|
False |
|
|
returnFaceLandmarks |
string
|
|
False |
Returns:
Type:array of (DetectResponseItem)
Summary: Add a person face
Description: Add a representative face to a person for identification.
Syntax:
FaceAPI.AddPersonFace (string personGroupId, string personId, AddPersonFaceParameterBody body, [advanced][Optional]string targetFace, [advanced][Optional]string userData)
Parameters:
|
Name |
Type |
Summary |
Required |
Related Action |
|
personGroupId |
string (Person Group Id) |
Person group |
True |
|
|
personId |
string (Person Id) |
Target person that the face is added to. |
True |
|
|
body |
|
|
True |
|
|
targetFace |
string (Target Face) |
A face rectangle to specify the target face to be added to a person, in the format of targetFace=left,top,width,height |
False |
|
|
userData |
string (User Data) |
User-specified data about the target face to add for any purpose. The maximum length is 1KB. |
False |
Returns:
Summary: Add face to face list
Description: Add face to face list.
Syntax:
FaceAPI.AddFaceToFaceList (AddFaceToFaceListParameterBody body, [advanced][Optional]string targetFace, [advanced][Optional]string userData, string faceListId)
Parameters:
|
Name |
Type |
Summary |
Required |
Related Action |
|
body |
AddFaceToFaceListParameterBody
|
|
True |
|
|
targetFace |
string (Target Face) |
A face rectangle to specify the target face to be added to a person, in the format of targetFace=left,top,width,height |
False |
|
|
userData |
string (User Data) |
User-specified data about the target face to add for any purpose. The maximum length is 1KB. |
False |
|
|
faceListId |
string (Face List Id) |
Valid character is letter in lower case or digit or '-' or '_', maximum length is 64. |
True |
Returns:
Summary: Get a person group
Description: Retrieve the information of a person group, including its name and userData.
Syntax:
FaceAPI.GetPersonGroup (string personGroupId)
Parameters:
|
Name |
Type |
Summary |
Required |
Related Action |
|
personGroupId |
string (Person Group Id) |
Target Person Group Id. |
True |
Returns:
Summary: Create a person group
Description: Create a new person group with specified personGroupId, name and user-provided userData.
Syntax:
FaceAPI.CreatePersonGroup (string personGroupId, CreatePersonGroupParameterBody body)
Parameters:
|
Name |
Type |
Summary |
Required |
Related Action |
|
personGroupId |
string (Person Group Id) |
New Person Group Id (valid characters include numbers, English letters in lower case, '-' and '_') |
True |
|
|
body |
CreatePersonGroupParameterBody
|
|
True |
Returns:
Summary: Find person from face
Description: Verify whether two faces belong to a same person or whether one face belongs to a person.
Syntax:
FaceAPI.Verify (VerifyParameterBody body)
Parameters:
|
Name |
Type |
Summary |
Required |
Related Action |
|
body |
|
|
True |
Returns:
Type:VerifyResponse
Summary: Get a person face
Description: Retrieve information about a persisted face specified by persistedFaceId, personId and its belonging personGroupId.
Syntax:
FaceAPI.GetPersonFace (string personGroupId, string personId, string persistedFaceId)
Parameters:
|
Name |
Type |
Summary |
Required |
Related Action |
|
personGroupId |
string (Person Group Id) |
Specifying the person group containing the target person. |
True |
|
|
personId |
string (Person Id) |
Specifying the target person that the face belongs to. |
True |
|
|
persistedFaceId |
string (Persisted Face Id) |
The persistedFaceId of the target persisted face of the person. |
True |
Returns:
Summary:
Description:
Syntax:
FaceAPI.GetPersonsInternal (string personGroupId)
Parameters:
|
Name |
Type |
Summary |
Required |
Related Action |
|
personGroupId |
string (personGroupId) |
|
True |
Returns:
Type:array of (GetPersonsInternalResponseItem)
Summary: Create a person
Description: Create a new person in a specified person group.
Syntax:
FaceAPI.CreatePerson (string personGroupId, CreatePersonParameterBody body)
Parameters:
|
Name |
Type |
Summary |
Required |
Related Action |
|
personGroupId |
string (Person Group Id) |
Specifying the target person group to create the person. |
True |
|
|
body |
|
|
True |
Returns:
Type:CreatePersonResponse
Summary: Get a person
Description: Retrieve a person's information, including registered persisted faces, name and userData.
Syntax:
FaceAPI.GetPerson (string personGroupId, string personId)
Parameters:
|
Name |
Type |
Summary |
Required |
Related Action |
|
personGroupId |
string (Person Group Id) |
Specifying the person group containing the target person. |
True |
|
|
personId |
string (Person Id) |
Specifying the target person. |
True |
Returns:
Type:GetPersonResponse
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
url |
string Image Url |
Image must be JPEG, PNG, GIF(the first frame), or BMP |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
url |
string Image Url |
Image must be JPEG, PNG, GIF(the first frame), or BMP |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
persistedFaceId |
string Persisted Face Id |
|
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
name |
string Face List Name |
Name of the created face list, maximum length is 128. |
|
userData |
string User Data |
Optional user defined data for the face list. Length should not exceed 16KB. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
name |
string Name |
Person group display name. The maximum length is 128. |
|
userData |
string User Data |
User-provided data attached to the person group. The size limit is 16KB. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
name |
string Name |
Display name of the target person. The maximum length is 128. |
|
userData |
string User Data |
Optional fields for user-provided data attached to a person. Size limit is 16KB. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
personId |
string Person Id |
|
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
url |
string Image Url |
Image must be JPEG, PNG, GIF(the first frame), or BMP |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
faceId |
string Face Id |
Unique faceId of the detected face. Will expire 24 hours after detection call. |
|
faceRectangle |
Face Rectangle |
|
|
faceLandmarks |
Face Landmarks |
|
|
faceAttributes |
|
|
Summary: Face Rectangle
Description:
Properties:
|
Name |
Type |
Summary |
|
top |
integer(int32) Top |
Parameters of a rectangle area for the face location on image. |
|
left |
integer(int32) Left |
Parameters of a rectangle area for the face location on image. |
|
width |
integer(int32) Width |
Parameters of a rectangle area for the face location on image. |
|
height |
integer(int32) Height |
Parameters of a rectangle area for the face location on image. |
Summary: Face Landmarks
Description:
Properties:
|
Name |
Type |
Summary |
|
pupilLeft |
|
|
|
pupilRight |
|
|
|
noseTip |
|
|
|
mouthLeft |
|
|
|
mouthRight |
|
|
|
eyebrowLeftOuter |
|
|
|
eyebrowLeftInner |
|
|
|
eyeLeftOuter |
|
|
|
eyeLeftTop |
|
|
|
eyeLeftBottom |
|
|
|
eyeLeftInner |
|
|
|
eyebrowRightInner |
|
|
|
eyebrowRightOuter |
|
|
|
eyeRightInner |
|
|
|
eyeRightTop |
|
|
|
eyeRightBottom |
|
|
|
eyeRightOuter |
|
|
|
noseRootLeft |
|
|
|
noseRootRight |
|
|
|
noseLeftAlarTop |
|
|
|
noseRightAlarTop |
|
|
|
noseLeftAlarOutTip |
|
|
|
noseRightAlarOutTip |
|
|
|
upperLipTop |
|
|
|
upperLipBottom |
|
|
|
underLipTop |
|
|
|
underLipBottom |
|
|
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Left Pupil X |
The x-coordinate of the left pupil. |
|
y |
number(float) Left Pupil Y |
The y-coordinate of the left pupil. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Right Pupil X |
The x-coordinate of the right pupil. |
|
y |
number(float) Right Pupil Y |
The y-coordinate of the right pupil. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Nose Tip X |
The x-coordinate of the nose tip. |
|
y |
number(float) Nose Tip Y |
The y-coordinate of the nose tip. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Mouth Left X |
The x-coordinate for the left side of the mouth. |
|
y |
number(float) Mouth Left Y |
The y-coordinate for the left side of the mouth. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Mouth Right X |
The x-coordinate for the right side of the mouth. |
|
y |
number(float) Mouth Right Y |
The y-coordinate for the right side of the mouth. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Outer Left Eyebrow X |
The x-coordinate for the outer side of the left eyebrow. |
|
y |
number(float) Outer Left Eyebrow Y |
The y-coordinate for the outer side of the left eyebrow. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Inner Left Eybrow X |
The x-coordinate for the inner side of the left eyebrow. |
|
y |
number(float) Inner Left Eyebrow Y |
The y-coordinate for the inner side of the left eyebrow. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Outer Left Eye X |
The x-coordinate for the outer side of the left eye. |
|
y |
number(float) Outer Left Eye Y |
The y-coordinate for the outer side of the left eye. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Top of Left Eye X |
The x-coordinate for the top of the left eye. |
|
y |
number(float) Top of Left Eye Y |
The y-coordinate for the top of the left eye. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Bottom of Left Eye X |
The x-coordinate for the bottom of the left eye. |
|
y |
number(float) Bottom of Left Eye Y |
The y-coordinate for the bottom of the left eye. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Inner Left Eye X |
The x-coordinate for the inner side of the left eye. |
|
y |
number(float) Inner Left Eye Y |
The y-coordinate for the inner side of the left eye. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Inner Right Eybrow X |
The x-coordinate for the inner side of the right eyebrow. |
|
y |
number(float) Inner Right Eyebrow Y |
The y-coordinate for the inner side of the right eyebrow. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Outer Right Eyebrow X |
The x-coordinate for the outer side of the right eyebrow. |
|
y |
number(float) Outer Right Eyebrow Y |
The y-coordinate for the outer side of the right eyebrow. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Inner Right Eye X |
The x-coordinate for the inner side of the right eye. |
|
y |
number(float) Inner Right Eye Y |
The y-coordinate for the inner side of the right eye. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Top of Right Eye X |
The x-coordinate for the top of the right eye. |
|
y |
number(float) Top of Right Eye Y |
The y-coordinate for the top of the right eye. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Bottom of Right Eye X |
The x-coordinate for the bottom of the right eye. |
|
y |
number(float) Bottom of Right Eye Y |
The y-coordinate for the bottom of the right eye. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Outer Right Eye X |
The x-coordinate for the outer side of the right eye. |
|
y |
number(float) Outer Right Eye Y |
The y-coordinate for the outer side of the right eye. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Left Nose Root X |
The x-coordinate for left side of the nose root. |
|
y |
number(float) Left Nose Root Y |
The y-coordinate for left side of the nose root. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Right Nose Root X |
The x-coordinate for right side of the nose root. |
|
y |
number(float) Right Nose Root Y |
The y-coordinate for right side of the nose root. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Top of Left Nose Altar X |
The x-coordinate for top of the left nose altar. |
|
y |
number(float) Top of Left Nose Altar Y |
The y-coordinate for top of the left nose altar. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Top of Right Nose Altar X |
The x-coordinate for top of the right nose altar. |
|
y |
number(float) Top of Right Nose Altar Y |
The y-coordinate for top of the right nose altar. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Tip of Left Nose Altar Out X |
The x-coordinate for tip of the left nose altar. |
|
y |
number(float) Tip of Left Nose Altar Out Y |
The y-coordinate for tip of the left nose altar/ |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Tip of Right Nose Altar Out X |
The x-coordinate for tip of the right nose altar. |
|
y |
number(float) Tip of Right Nose Altar Out Y |
The y-coordinate for tip of the right nose altar. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Top of Upper Lip X |
The x-coordinate for top of upper lip. |
|
y |
number(float) Top of Upper Lip Y |
The y-coordinate for top of upper lip. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Bottom of Upper Lip X |
The x-coordinate for bottom of upper lip. |
|
y |
number(float) Bottom of Upper Lip Y |
The y-coordinate for bottom of upper lip. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Top of Under Lip X |
The x-coordinate for top of under lip. |
|
y |
number(float) Top of Under Lip Y |
The y-coordinate for top of under lip. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
x |
number(float) Bottom of Under Lip X |
The x-coordinate for bottom of under lip. |
|
y |
number(float) Bottom of Under Lip Y |
The y-coordinate for bottom of under lip. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
smile |
number(float) Smile |
Intensity between [0,1]. |
|
headPose |
|
|
|
gender |
string Gender |
Male for female. |
|
age |
number(float) Age |
Age of person. |
|
facialHair |
|
|
|
glasses |
string Glasses |
Type of glasses. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
pitch |
number(float) Head Pose Pitch |
Reserved field, always returns 0. |
|
roll |
number(float) Head Pose Roll |
Roll of the head pose. |
|
yaw |
number(float) Head Pose Yaw |
Yaw of the head pose. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
moustache |
number(float) Moustache |
Intensity between [0,1]. |
|
beard |
number(float) Beard |
Intensity between [0,1]. |
|
sideburns |
number(float) Sideburns |
Intensity between [0,1]. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
faceListId |
string Face List Id |
|
|
name |
string Name |
|
|
userData |
string User Data |
|
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
persistedFaces |
array of (PersistedFacesItem) Persisted Faces |
|
|
faceListId |
string Face List Id |
faceListId of the target face list. |
|
name |
string Name |
Face list's display name. |
|
userData |
string User Data |
User-provided data attached to the face list. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
persistedFaceId |
string Persisted Face Id |
Id of the face. |
|
userData |
string User Data |
User-provided data attached to each face. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
persistedFaceId |
string Persisted Face Id |
|
|
userData |
string
|
|
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
personGroupId |
string Person Group Id |
|
|
name |
string Name |
|
|
userData |
string
|
|
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
personGroupId |
string
|
|
|
name |
string
|
|
|
userData |
string
|
|
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
personId |
string Person Id |
|
|
persistedFaceIds |
array of (PersistedFaceIdsItem) Persisted Face Ids |
|
|
name |
string Name |
|
|
userData |
string User Data |
|
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
persistedFaceId |
string Persisted Face Id |
|
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
personId |
string
|
|
|
persistedFaceIds |
array of (string)
|
|
|
name |
string
|
|
|
userData |
string
|
|
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
faceId |
string Face Id |
Unique faceId of the detected face. Will expire 24 hours after detection call. |
|
personGroupId |
string Person Group Id |
Person Group Id created in Face API - Create Person Group action. |
|
personId |
string Person Id |
Person Id created in Face API - Create Person action. |
Summary:
Description:
Properties:
|
Name |
Type |
Summary |
|
isIdentical |
boolean Is Identical |
True if the two faces belong to the same person or the face belongs to the person, otherwise false. |
|
confidence |
number(float) Confidence |
A number indicates the similarity confidence of whether two faces belong to the same person, or whether the face belongs to the person. |