Connectors Reference

Face API

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

 

Actions:

Name

Summary

GetFaceListInternal ()

 

GetPersonGroupsInternal ()

 

GetFaceList (string faceListId)

Get a face list

CreateFaceList (string faceListId, CreateFaceListParameterBody body)

Create a face list

Detect ([internal][Optional]string returnFaceId, DetectParameterBody body, [internal][Optional]string returnFaceAttributes, [internal][Optional]string returnFaceLandmarks)

Detect faces

AddPersonFace (string personGroupId, string personId, AddPersonFaceParameterBody body, [advanced][Optional]string targetFace, [advanced][Optional]string userData)

Add a person face

AddFaceToFaceList (AddFaceToFaceListParameterBody body, [advanced][Optional]string targetFace, [advanced][Optional]string userData, string faceListId)

Add face to face list

GetPersonGroup (string personGroupId)

Get a person group

CreatePersonGroup (string personGroupId, CreatePersonGroupParameterBody body)

Create a person group

Verify (VerifyParameterBody body)

Find person from face

GetPersonFace (string personGroupId, string personId, string persistedFaceId)

Get a person face

GetPersonsInternal (string personGroupId)

 

CreatePerson (string personGroupId, CreatePersonParameterBody body)

Create a person

GetPerson (string personGroupId, string personId)

Get a person

 

Triggers:

Name

Summary

 

Objects:

Name

Summary

AddFaceToFaceListParameterBody

 

AddPersonFaceParameterBody

 

AddPersonFaceResponse

 

CreateFaceListParameterBody

 

CreatePersonGroupParameterBody

 

CreatePersonParameterBody

 

CreatePersonResponse

 

DetectParameterBody

 

DetectResponseItem

 

GetFaceListInternalResponseItem

 

GetFaceListResponse

 

GetPersonFaceResponse

 

GetPersonGroupResponse

 

GetPersonGroupsInternalResponseItem

 

GetPersonResponse

 

GetPersonsInternalResponseItem

 

VerifyParameterBody

 

VerifyResponse

 

 

Actions:

GetFaceListInternal

Summary:

Description:

 

Syntax:

FaceAPI.GetFaceListInternal ()

 

Returns:

          Type:array of (GetFaceListInternalResponseItem)

 

GetPersonGroupsInternal

Summary:

Description:

 

Syntax:

FaceAPI.GetPersonGroupsInternal ()

 

Returns:

          Type:array of (GetPersonGroupsInternalResponseItem)

 

GetFaceList

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

GetFaceListInternal

 

Returns:

          Type:GetFaceListResponse

 

CreateFaceList

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

CreateFaceListParameterBody

 

 

True

 

Returns:

 

Detect

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

DetectParameterBody

 

 

True

returnFaceAttributes

string

 

 

False

returnFaceLandmarks

string

 

 

False

 

Returns:

          Type:array of (DetectResponseItem)

 

AddPersonFace

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

GetPersonGroupsInternal

personId

string

(Person Id)

Target person that the face is added to.

True

GetPersonsInternal

body

AddPersonFaceParameterBody

 

 

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:

          Type:AddPersonFaceResponse

 

AddFaceToFaceList

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

GetFaceListInternal

 

Returns:

          Type:AddPersonFaceResponse

 

GetPersonGroup

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

GetPersonGroupsInternal

 

Returns:

          Type:GetPersonGroupResponse

 

CreatePersonGroup

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:

 

Verify

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

VerifyParameterBody

 

 

True

 

Returns:

          Type:VerifyResponse

 

GetPersonFace

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

GetPersonGroupsInternal

personId

string

(Person Id)

Specifying the target person that the face belongs to.

True

GetPersonsInternal

persistedFaceId

string

(Persisted Face Id)

The persistedFaceId of the target persisted face of the person.

True

GetPerson

 

Returns:

          Type:GetPersonFaceResponse

 

GetPersonsInternal

Summary:

Description:

 

Syntax:

FaceAPI.GetPersonsInternal (string personGroupId)

 

Parameters:

Name

Type

Summary

Required

Related Action

personGroupId

string

(personGroupId)

 

True

 

Returns:

          Type:array of (GetPersonsInternalResponseItem)

 

CreatePerson

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

GetPersonGroupsInternal

body

CreatePersonParameterBody

 

 

True

 

Returns:

          Type:CreatePersonResponse

 

GetPerson

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

GetPersonGroupsInternal

personId

string

(Person Id)

Specifying the target person.

True

GetPersonsInternal

 

Returns:

          Type:GetPersonResponse

 


 

AddFaceToFaceListParameterBody

Summary:

Description:

 

          Properties:

Name

Type

Summary

url

string

Image Url

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


 

AddPersonFaceParameterBody

Summary:

Description:

 

          Properties:

Name

Type

Summary

url

string

Image Url

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


 

AddPersonFaceResponse

Summary:

Description:

 

          Properties:

Name

Type

Summary

persistedFaceId

string

Persisted Face Id

 


 

CreateFaceListParameterBody

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.


 

CreatePersonGroupParameterBody

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.


 

CreatePersonParameterBody

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.


 

CreatePersonResponse

Summary:

Description:

 

          Properties:

Name

Type

Summary

personId

string

Person Id

 


 

DetectParameterBody

Summary:

Description:

 

          Properties:

Name

Type

Summary

url

string

Image Url

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


 

DetectResponseItem

Summary:

Description:

 

          Properties:

Name

Type

Summary

faceId

string

Face Id

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

faceRectangle

FaceRectangle

Face Rectangle

 

faceLandmarks

FaceLandmarks

Face Landmarks

 

faceAttributes

FaceAttributes

 

 

 

FaceRectangle

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.

 

FaceLandmarks

Summary: Face Landmarks

Description:

 

          Properties:

Name

Type

Summary

pupilLeft

PupilLeft

 

 

pupilRight

PupilRight

 

 

noseTip

NoseTip

 

 

mouthLeft

MouthLeft

 

 

mouthRight

MouthRight

 

 

eyebrowLeftOuter

EyebrowLeftOuter

 

 

eyebrowLeftInner

EyebrowLeftInner

 

 

eyeLeftOuter

EyeLeftOuter

 

 

eyeLeftTop

EyeLeftTop

 

 

eyeLeftBottom

EyeLeftBottom

 

 

eyeLeftInner

EyeLeftInner

 

 

eyebrowRightInner

EyebrowRightInner

 

 

eyebrowRightOuter

EyebrowRightOuter

 

 

eyeRightInner

EyeRightInner

 

 

eyeRightTop

EyeRightTop

 

 

eyeRightBottom

EyeRightBottom

 

 

eyeRightOuter

EyeRightOuter

 

 

noseRootLeft

NoseRootLeft

 

 

noseRootRight

NoseRootRight

 

 

noseLeftAlarTop

NoseLeftAlarTop

 

 

noseRightAlarTop

NoseRightAlarTop

 

 

noseLeftAlarOutTip

NoseLeftAlarOutTip

 

 

noseRightAlarOutTip

NoseRightAlarOutTip

 

 

upperLipTop

UpperLipTop

 

 

upperLipBottom

UpperLipBottom

 

 

underLipTop

UnderLipTop

 

 

underLipBottom

UnderLipBottom

 

 

 

PupilLeft

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.

 

PupilRight

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.

 

NoseTip

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.

 

MouthLeft

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.

 

MouthRight

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.

 

EyebrowLeftOuter

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.

 

EyebrowLeftInner

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.

 

EyeLeftOuter

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.

 

EyeLeftTop

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.

 

EyeLeftBottom

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.

 

EyeLeftInner

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.

 

EyebrowRightInner

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.

 

EyebrowRightOuter

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.

 

EyeRightInner

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.

 

EyeRightTop

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.

 

EyeRightBottom

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.

 

EyeRightOuter

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.

 

NoseRootLeft

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.

 

NoseRootRight

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.

 

NoseLeftAlarTop

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.

 

NoseRightAlarTop

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.

 

NoseLeftAlarOutTip

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/

 

NoseRightAlarOutTip

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.

 

UpperLipTop

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.

 

UpperLipBottom

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.

 

UnderLipTop

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.

 

UnderLipBottom

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.

 

FaceAttributes

Summary:

Description:

 

          Properties:

Name

Type

Summary

smile

number(float)

Smile

Intensity between [0,1].

headPose

HeadPose

 

 

gender

string

Gender

Male for female.

age

number(float)

Age

Age of person.

facialHair

FacialHair

 

 

glasses

string

Glasses

Type of glasses.

 

HeadPose

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.

 

FacialHair

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

 


 

GetFaceListInternalResponseItem

Summary:

Description:

 

          Properties:

Name

Type

Summary

faceListId

string

Face List Id

 

name

string

Name

 

userData

string

User Data

 


 

GetFaceListResponse

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.

 

PersistedFacesItem

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.

 


 

GetPersonFaceResponse

Summary:

Description:

 

          Properties:

Name

Type

Summary

persistedFaceId

string

Persisted Face Id

 

userData

string

 

 


 

GetPersonGroupResponse

Summary:

Description:

 

          Properties:

Name

Type

Summary

personGroupId

string

Person Group Id

 

name

string

Name

 

userData

string

 

 


 

GetPersonGroupsInternalResponseItem

Summary:

Description:

 

          Properties:

Name

Type

Summary

personGroupId

string

 

 

name

string

 

 

userData

string

 

 


 

GetPersonResponse

Summary:

Description:

 

          Properties:

Name

Type

Summary

personId

string

Person Id

 

persistedFaceIds

array of (string)

Persisted Face Ids

 

name

string

Name

 

userData

string

User Data

 


 

GetPersonsInternalResponseItem

Summary:

Description:

 

          Properties:

Name

Type

Summary

personId

string

 

 

persistedFaceIds

array of (string)

 

 

name

string

 

 

userData

string

 

 


 

VerifyParameterBody

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.


 

VerifyResponse

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.