@datafire/azure_cognitiveservices_face v4.0.0
@datafire/azure_cognitiveservices_face
Client library for Face Client
Installation and Usage
npm install --save @datafire/azure_cognitiveservices_face
let azure_cognitiveservices_face = require('@datafire/azure_cognitiveservices_face').create({
apim_key: ""
});
.then(data => {
console.log(data);
});
Description
An API for face detection, verification, and identification.
Actions
Face_DetectWithUrl
Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.
- No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in Face - Identify, Face - Verify, and Face - Find Similar. The stored face feature(s) will expire and be deleted 24 hours after the original detection call.
- Optional parameters include faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. Some of the results returned for specific attributes may not be highly accurate.
- JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB.
- Up to 100 faces can be returned for an image. Faces are ranked by face rectangle size from large to small.
- For optimal results when querying Face - Identify, Face - Verify, and Face - Find Similar ('returnFaceId' is true), please use faces that are: frontal, clear, and with a minimum size of 200x200 pixels (100 pixels between eyes).
- The minimum detectable face size is 36x36 pixels in an image no larger than 1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels will need a proportionally larger minimum face size.
Different 'detectionModel' values can be provided. To use and compare different detection models, please refer to How to specify a detection model | Model | Recommended use-case(s) | | ---------- | -------- | | 'detection_01': | The default detection model for Face - Detect. Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. | | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |
Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to How to specify a recognition model | Model | Recommended use-case(s) | | ---------- | -------- | | 'recognition_01': | The default recognition model for Face - Detect. All those faceIds created before 2019 March are bonded with this recognition model. | | 'recognition_02': | Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. |
azure_cognitiveservices_face.Face_DetectWithUrl({
"ImageUrl": {
"url": ""
}
}, context)
Input
- input
object
- returnFaceId
boolean
: A value indicating whether the operation should return faceIds of detected faces. - returnFaceLandmarks
boolean
: A value indicating whether the operation should return landmarks of the detected faces. - returnFaceAttributes
array
: Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. - ImageUrl required
object
- url required
string
: Publicly reachable URL of an image
- url required
- recognitionModel
string
(values: recognition_01, recognition_02): Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. - returnRecognitionModel
boolean
: A value indicating whether the operation should return 'recognitionModel' in response. - detectionModel
string
(values: detection_01, detection_02): Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when performing Face - Detect or (Large)FaceList - Add Face or (Large)PersonGroup - Add Face. The default value is 'detection_01', if another model is needed, please explicitly specify it.
- returnFaceId
Output
- output DetectedFaces
FaceList_List
List face lists’ faceListId, name, userData and recognitionModel. To get face information inside faceList use FaceList - Get
azure_cognitiveservices_face.FaceList_List({}, context)
Input
- input
object
- returnRecognitionModel
boolean
: A value indicating whether the operation should return 'recognitionModel' in response.
- returnRecognitionModel
Output
- output FaceLists
FaceList_Delete
Delete a specified face list.
azure_cognitiveservices_face.FaceList_Delete({
"faceListId": ""
}, context)
Input
- input
object
- faceListId required
string
: Id referencing a particular face list.
- faceListId required
Output
Output schema unknown
FaceList_Get
Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list.
azure_cognitiveservices_face.FaceList_Get({
"faceListId": ""
}, context)
Input
- input
object
- faceListId required
string
: Id referencing a particular face list. - returnRecognitionModel
boolean
: A value indicating whether the operation should return 'recognitionModel' in response.
- faceListId required
Output
- output FaceList
FaceList_Update
Update information of a face list.
azure_cognitiveservices_face.FaceList_Update({
"faceListId": "",
"body": {}
}, context)
Input
- input
object
- faceListId required
string
: Id referencing a particular face list. - body required NameAndUserDataContract
- faceListId required
Output
Output schema unknown
FaceList_Create
Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. Face list is a list of faces, up to 1,000 faces, and used by Face - Find Similar. After creation, user should use FaceList - Add Face to import the faces. No image will be stored. Only the extracted face features are stored on server until FaceList - Delete is called. Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use PersonGroup / LargePersonGroup and Face - Identify. Please consider LargeFaceList when the face number is large. It can support up to 1,000,000 faces. 'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model.
- 'recognition_01': The default recognition model for FaceList- Create. All those face lists created before 2019 March are bonded with this recognition model.
- 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'.
azure_cognitiveservices_face.FaceList_Create({
"faceListId": "",
"body": {}
}, context)
Input
- input
object
- faceListId required
string
: Id referencing a particular face list. - body required MetaDataContract
- faceListId required
Output
Output schema unknown
FaceList_AddFaceFromUrl
Add a face to a specified face list, up to 1,000 faces. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until FaceList - Delete Face or FaceList - Delete is called. Note persistedFaceId is different from faceId generated by Face - Detect.
- Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
- JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB.
- "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from Face - Detect, there’s no guarantee to detect and add the face successfully.
- Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures.
- Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel.
- The minimum detectable face size is 36x36 pixels in an image no larger than 1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels will need a proportionally larger minimum face size.
- Different 'detectionModel' values can be provided. To use and compare different detection models, please refer to How to specify a detection model | Model | Recommended use-case(s) | | ---------- | -------- | | 'detection_01': | The default detection model for FaceList - Add Face. Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. | | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |
azure_cognitiveservices_face.FaceList_AddFaceFromUrl({
"faceListId": "",
"ImageUrl": {
"url": ""
}
}, context)
Input
- input
object
- faceListId required
string
: Id referencing a particular face list. - userData
string
: User-specified data about the face for any purpose. The maximum length is 1KB. - targetFace
array
: A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. - ImageUrl required
object
- url required
string
: Publicly reachable URL of an image
- url required
- detectionModel
string
(values: detection_01, detection_02): Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when performing Face - Detect or (Large)FaceList - Add Face or (Large)PersonGroup - Add Face. The default value is 'detection_01', if another model is needed, please explicitly specify it.
- faceListId required
Output
- output PersistedFace
FaceList_DeleteFace
Delete a face from a face list by specified faceListId and persistedFaceId. Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel.
azure_cognitiveservices_face.FaceList_DeleteFace({
"faceListId": "",
"persistedFaceId": ""
}, context)
Input
- input
object
- faceListId required
string
: Id referencing a particular face list. - persistedFaceId required
string
: Id referencing a particular persistedFaceId of an existing face.
- faceListId required
Output
Output schema unknown
Face_FindSimilar
Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by Face - Detect, which will expire 24 hours after creation. A "faceListId" is created by FaceList - Create containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by LargeFaceList - Create containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list.
azure_cognitiveservices_face.Face_FindSimilar({
"body": {
"faceId": ""
}
}, context)
Input
- input
object
- body required FindSimilarRequest
Output
- output SimilarFaces
Face_Group
Divide candidate faces into groups based on face similarity.
- The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result.
- MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts.
- Group API needs at least 2 candidate faces and 1000 at most. We suggest to try Face - Verify when you only have 2 candidate faces.
- The 'recognitionModel' associated with the query faces' faceIds should be the same.
azure_cognitiveservices_face.Face_Group({
"body": {
"faceIds": []
}
}, context)
Input
- input
object
- body required GroupRequest
Output
- output GroupResult
Face_Identify
1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in PersonGroup - Train and LargePersonGroup - Train.
Remarks:
- The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces.
- Each person in the person group/large person group could have more than one face, but no more than 248 faces.
- Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
- Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array.
- Try Face - Find Similar when you need to find similar faces from a face list/large face list instead of a person group/large person group.
- The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group.
azure_cognitiveservices_face.Face_Identify({
"body": {
"faceIds": []
}
}, context)
Input
- input
object
- body required IdentifyRequest
Output
- output IdentifyResults
LargeFaceList_List
List large face lists’ information of largeFaceListId, name, userData and recognitionModel. To get face information inside largeFaceList use LargeFaceList Face - Get
- Large face lists are stored in alphabetical order of largeFaceListId.
- "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item.
- "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. For example, total 5 large person lists: "list1", ..., "list5". "start=&top=" will return all 5 lists. "start=&top=2" will return "list1", "list2". "start=list2&top=3" will return "list3", "list4", "list5".
azure_cognitiveservices_face.LargeFaceList_List({}, context)
Input
- input
object
- returnRecognitionModel
boolean
: A value indicating whether the operation should return 'recognitionModel' in response.
- returnRecognitionModel
Output
- output LargeFaceLists
LargeFaceList_Delete
Delete a specified large face list.
azure_cognitiveservices_face.LargeFaceList_Delete({
"largeFaceListId": ""
}, context)
Input
- input
object
- largeFaceListId required
string
: Id referencing a particular large face list.
- largeFaceListId required
Output
Output schema unknown
LargeFaceList_Get
Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel.
azure_cognitiveservices_face.LargeFaceList_Get({
"largeFaceListId": ""
}, context)
Input
- input
object
- largeFaceListId required
string
: Id referencing a particular large face list. - returnRecognitionModel
boolean
: A value indicating whether the operation should return 'recognitionModel' in response.
- largeFaceListId required
Output
- output LargeFaceList
LargeFaceList_Update
Update information of a large face list.
azure_cognitiveservices_face.LargeFaceList_Update({
"largeFaceListId": "",
"body": {}
}, context)
Input
- input
object
- largeFaceListId required
string
: Id referencing a particular large face list. - body required NameAndUserDataContract
- largeFaceListId required
Output
Output schema unknown
LargeFaceList_Create
Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. Large face list is a list of faces, up to 1,000,000 faces, and used by Face - Find Similar. After creation, user should use LargeFaceList Face - Add to import the faces and LargeFaceList - Train to make it ready for Face - Find Similar. No image will be stored. Only the extracted face features are stored on server until LargeFaceList - Delete is called. Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use PersonGroup / LargePersonGroup and Face - Identify. 'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model.
- 'recognition_01': The default recognition model for LargeFaceList- Create. All those large face lists created before 2019 March are bonded with this recognition model.
- 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'.
Large face list quota:
- Free-tier subscription quota: 64 large face lists.
- S0-tier subscription quota: 1,000,000 large face lists.
azure_cognitiveservices_face.LargeFaceList_Create({
"largeFaceListId": "",
"body": {}
}, context)
Input
- input
object
- largeFaceListId required
string
: Id referencing a particular large face list. - body required MetaDataContract
- largeFaceListId required
Output
Output schema unknown
LargeFaceList_ListFaces
List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face).
azure_cognitiveservices_face.LargeFaceList_ListFaces({
"largeFaceListId": ""
}, context)
Input
- input
object
- largeFaceListId required
string
: Id referencing a particular large face list. - start
string
: Starting face id to return (used to list a range of faces). - top
integer
: Number of faces to return starting with the face id indicated by the 'start' parameter.
- largeFaceListId required
Output
- output PersistedFaces
LargeFaceList_AddFaceFromUrl
Add a face to a specified large face list, up to 1,000,000 faces. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until LargeFaceList Face - Delete or LargeFaceList - Delete is called. Note persistedFaceId is different from faceId generated by Face - Detect.
- Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
- JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB.
- "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from Face - Detect, there’s no guarantee to detect and add the face successfully.
- Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures.
- Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel.
- The minimum detectable face size is 36x36 pixels in an image no larger than 1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels will need a proportionally larger minimum face size.
- Different 'detectionModel' values can be provided. To use and compare different detection models, please refer to How to specify a detection model | Model | Recommended use-case(s) | | ---------- | -------- | | 'detection_01': | The default detection model for LargeFaceList - Add Face. Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. | | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |
Quota:
- Free-tier subscription quota: 1,000 faces per large face list.
- S0-tier subscription quota: 1,000,000 faces per large face list.
azure_cognitiveservices_face.LargeFaceList_AddFaceFromUrl({
"largeFaceListId": "",
"ImageUrl": {
"url": ""
}
}, context)
Input
- input
object
- largeFaceListId required
string
: Id referencing a particular large face list. - userData
string
: User-specified data about the face for any purpose. The maximum length is 1KB. - targetFace
array
: A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. - ImageUrl required
object
- url required
string
: Publicly reachable URL of an image
- url required
- detectionModel
string
(values: detection_01, detection_02): Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when performing Face - Detect or (Large)FaceList - Add Face or (Large)PersonGroup - Add Face. The default value is 'detection_01', if another model is needed, please explicitly specify it.
- largeFaceListId required
Output
- output PersistedFace
LargeFaceList_DeleteFace
Delete a face from a large face list by specified largeFaceListId and persistedFaceId. Adding/deleting faces to/from a same large face list are processed sequentially and to/from different large face lists are in parallel.
azure_cognitiveservices_face.LargeFaceList_DeleteFace({
"largeFaceListId": "",
"persistedFaceId": ""
}, context)
Input
- input
object
- largeFaceListId required
string
: Id referencing a particular large face list. - persistedFaceId required
string
: Id referencing a particular persistedFaceId of an existing face.
- largeFaceListId required
Output
Output schema unknown
LargeFaceList_GetFace
Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId).
azure_cognitiveservices_face.LargeFaceList_GetFace({
"largeFaceListId": "",
"persistedFaceId": ""
}, context)
Input
- input
object
- largeFaceListId required
string
: Id referencing a particular large face list. - persistedFaceId required
string
: Id referencing a particular persistedFaceId of an existing face.
- largeFaceListId required
Output
- output PersistedFace
LargeFaceList_UpdateFace
Update a persisted face's userData field.
azure_cognitiveservices_face.LargeFaceList_UpdateFace({
"largeFaceListId": "",
"persistedFaceId": "",
"body": {}
}, context)
Input
- input
object
- largeFaceListId required
string
: Id referencing a particular large face list. - persistedFaceId required
string
: Id referencing a particular persistedFaceId of an existing face. - body required UpdateFaceRequest
- largeFaceListId required
Output
Output schema unknown
LargeFaceList_Train
Queue a large face list training task, the training task may not be started immediately.
azure_cognitiveservices_face.LargeFaceList_Train({
"largeFaceListId": ""
}, context)
Input
- input
object
- largeFaceListId required
string
: Id referencing a particular large face list.
- largeFaceListId required
Output
Output schema unknown
LargeFaceList_GetTrainingStatus
Retrieve the training status of a large face list (completed or ongoing).
azure_cognitiveservices_face.LargeFaceList_GetTrainingStatus({
"largeFaceListId": ""
}, context)
Input
- input
object
- largeFaceListId required
string
: Id referencing a particular large face list.
- largeFaceListId required
Output
- output TrainingStatus
LargePersonGroup_List
List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.
- Large person groups are stored in alphabetical order of largePersonGroupId.
- "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item.
- "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. For example, total 5 large person groups: "group1", ..., "group5". "start=&top=" will return all 5 groups. "start=&top=2" will return "group1", "group2". "start=group2&top=3" will return "group3", "group4", "group5".
azure_cognitiveservices_face.LargePersonGroup_List({}, context)
Input
- input
object
- start
string
: List large person groups from the least largePersonGroupId greater than the "start". - top
integer
: The number of large person groups to list. - returnRecognitionModel
boolean
: A value indicating whether the operation should return 'recognitionModel' in response.
- start
Output
- output LargePersonGroups
LargePersonGroup_Delete
Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted.
azure_cognitiveservices_face.LargePersonGroup_Delete({
"largePersonGroupId": ""
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group.
- largePersonGroupId required
Output
Output schema unknown
LargePersonGroup_Get
Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use LargePersonGroup Person - List instead to retrieve person information under the large person group.
azure_cognitiveservices_face.LargePersonGroup_Get({
"largePersonGroupId": ""
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group. - returnRecognitionModel
boolean
: A value indicating whether the operation should return 'recognitionModel' in response.
- largePersonGroupId required
Output
- output LargePersonGroup
LargePersonGroup_Update
Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated.
azure_cognitiveservices_face.LargePersonGroup_Update({
"largePersonGroupId": "",
"body": {}
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group. - body required NameAndUserDataContract
- largePersonGroupId required
Output
Output schema unknown
LargePersonGroup_Create
Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 people. After creation, use LargePersonGroup Person - Create to add person into the group, and call LargePersonGroup - Train to get this group ready for Face - Identify. No image will be stored. Only the person's extracted face features and userData will be stored on server until LargePersonGroup Person - Delete or LargePersonGroup - Delete is called. 'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model.
- 'recognition_01': The default recognition model for LargePersonGroup - Create. All those large person groups created before 2019 March are bonded with this recognition model.
- 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'.
Large person group quota:
- Free-tier subscription quota: 1,000 large person groups.
- S0-tier subscription quota: 1,000,000 large person groups.
azure_cognitiveservices_face.LargePersonGroup_Create({
"largePersonGroupId": "",
"body": {}
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group. - body required MetaDataContract
- largePersonGroupId required
Output
Output schema unknown
LargePersonGroupPerson_List
List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person).
azure_cognitiveservices_face.LargePersonGroupPerson_List({
"largePersonGroupId": ""
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group. - start
string
: Starting person id to return (used to list a range of persons). - top
integer
: Number of persons to return starting with the person id indicated by the 'start' parameter.
- largePersonGroupId required
Output
- output Persons
LargePersonGroupPerson_Create
Create a new person in a specified large person group.
azure_cognitiveservices_face.LargePersonGroupPerson_Create({
"largePersonGroupId": "",
"body": {}
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group. - body required NameAndUserDataContract
- largePersonGroupId required
Output
- output Person
LargePersonGroupPerson_Delete
Delete an existing person from a large person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted.
azure_cognitiveservices_face.LargePersonGroupPerson_Delete({
"largePersonGroupId": "",
"personId": ""
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group. - personId required
string
: Id referencing a particular person.
- largePersonGroupId required
Output
Output schema unknown
LargePersonGroupPerson_Get
Retrieve a person's name and userData, and the persisted faceIds representing the registered person face feature.
azure_cognitiveservices_face.LargePersonGroupPerson_Get({
"largePersonGroupId": "",
"personId": ""
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group. - personId required
string
: Id referencing a particular person.
- largePersonGroupId required
Output
- output Person
LargePersonGroupPerson_Update
Update name or userData of a person.
azure_cognitiveservices_face.LargePersonGroupPerson_Update({
"largePersonGroupId": "",
"personId": "",
"body": {}
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group. - personId required
string
: Id referencing a particular person. - body required NameAndUserDataContract
- largePersonGroupId required
Output
Output schema unknown
LargePersonGroupPerson_AddFaceFromUrl
Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until LargePersonGroup PersonFace - Delete, LargePersonGroup Person - Delete or LargePersonGroup - Delete is called. Note persistedFaceId is different from faceId generated by Face - Detect.
- Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
- Each person entry can hold up to 248 faces.
- JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB.
- "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from Face - Detect, there’s no guarantee to detect and add the face successfully.
- Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures.
- Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel.
- The minimum detectable face size is 36x36 pixels in an image no larger than 1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels will need a proportionally larger minimum face size.
- Different 'detectionModel' values can be provided. To use and compare different detection models, please refer to How to specify a detection model | Model | Recommended use-case(s) | | ---------- | -------- | | 'detection_01': | The default detection model for LargePersonGroup Person - Add Face. Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. | | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |
azure_cognitiveservices_face.LargePersonGroupPerson_AddFaceFromUrl({
"largePersonGroupId": "",
"personId": "",
"ImageUrl": {
"url": ""
}
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group. - personId required
string
: Id referencing a particular person. - userData
string
: User-specified data about the face for any purpose. The maximum length is 1KB. - targetFace
array
: A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. - ImageUrl required
object
- url required
string
: Publicly reachable URL of an image
- url required
- detectionModel
string
(values: detection_01, detection_02): Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when performing Face - Detect or (Large)FaceList - Add Face or (Large)PersonGroup - Add Face. The default value is 'detection_01', if another model is needed, please explicitly specify it.
- largePersonGroupId required
Output
- output PersistedFace
LargePersonGroupPerson_DeleteFace
Delete a face from a person in a large person group by specified largePersonGroupId, personId and persistedFaceId. Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel.
azure_cognitiveservices_face.LargePersonGroupPerson_DeleteFace({
"largePersonGroupId": "",
"personId": "",
"persistedFaceId": ""
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group. - personId required
string
: Id referencing a particular person. - persistedFaceId required
string
: Id referencing a particular persistedFaceId of an existing face.
- largePersonGroupId required
Output
Output schema unknown
LargePersonGroupPerson_GetFace
Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId).
azure_cognitiveservices_face.LargePersonGroupPerson_GetFace({
"largePersonGroupId": "",
"personId": "",
"persistedFaceId": ""
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group. - personId required
string
: Id referencing a particular person. - persistedFaceId required
string
: Id referencing a particular persistedFaceId of an existing face.
- largePersonGroupId required
Output
- output PersistedFace
LargePersonGroupPerson_UpdateFace
Update a person persisted face's userData field.
azure_cognitiveservices_face.LargePersonGroupPerson_UpdateFace({
"largePersonGroupId": "",
"personId": "",
"persistedFaceId": "",
"body": {}
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group. - personId required
string
: Id referencing a particular person. - persistedFaceId required
string
: Id referencing a particular persistedFaceId of an existing face. - body required UpdateFaceRequest
- largePersonGroupId required
Output
Output schema unknown
LargePersonGroup_Train
Queue a large person group training task, the training task may not be started immediately.
azure_cognitiveservices_face.LargePersonGroup_Train({
"largePersonGroupId": ""
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group.
- largePersonGroupId required
Output
Output schema unknown
LargePersonGroup_GetTrainingStatus
Retrieve the training status of a large person group (completed or ongoing).
azure_cognitiveservices_face.LargePersonGroup_GetTrainingStatus({
"largePersonGroupId": ""
}, context)
Input
- input
object
- largePersonGroupId required
string
: Id referencing a particular large person group.
- largePersonGroupId required
Output
- output TrainingStatus
Snapshot_GetOperationStatus
Retrieve the status of a take/apply snapshot operation.
azure_cognitiveservices_face.Snapshot_GetOperationStatus({
"operationId": ""
}, context)
Input
- input
object
- operationId required
string
: Id referencing a particular take/apply snapshot operation.
- operationId required
Output
- output OperationStatus
PersonGroup_List
List person groups’ personGroupId, name, userData and recognitionModel.
- Person groups are stored in alphabetical order of personGroupId.
- "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item.
- "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. For example, total 5 person groups: "group1", ..., "group5". "start=&top=" will return all 5 groups. "start=&top=2" will return "group1", "group2". "start=group2&top=3" will return "group3", "group4", "group5".
azure_cognitiveservices_face.PersonGroup_List({}, context)
Input
- input
object
- start
string
: List person groups from the least personGroupId greater than the "start". - top
integer
: The number of person groups to list. - returnRecognitionModel
boolean
: A value indicating whether the operation should return 'recognitionModel' in response.
- start
Output
- output PersonGroups
PersonGroup_Delete
Delete an existing person group. Persisted face features of all people in the person group will also be deleted.
azure_cognitiveservices_face.PersonGroup_Delete({
"personGroupId": ""
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group.
- personGroupId required
Output
Output schema unknown
PersonGroup_Get
Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use PersonGroup Person - List.
azure_cognitiveservices_face.PersonGroup_Get({
"personGroupId": ""
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group. - returnRecognitionModel
boolean
: A value indicating whether the operation should return 'recognitionModel' in response.
- personGroupId required
Output
- output PersonGroup
PersonGroup_Update
Update an existing person group's display name and userData. The properties which does not appear in request body will not be updated.
azure_cognitiveservices_face.PersonGroup_Update({
"personGroupId": "",
"body": {}
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group. - body required NameAndUserDataContract
- personGroupId required
Output
Output schema unknown
PersonGroup_Create
Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. A person group is the container of the uploaded person data, including face recognition features. After creation, use PersonGroup Person - Create to add persons into the group, and then call PersonGroup - Train to get this group ready for Face - Identify. No image will be stored. Only the person's extracted face features and userData will be stored on server until PersonGroup Person - Delete or PersonGroup - Delete is called. 'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model.
- 'recognition_01': The default recognition model for PersonGroup - Create. All those person groups created before 2019 March are bonded with this recognition model.
- 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'.
Person group quota:
- Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons.
- S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons.
- to handle larger scale face identification problem, please consider using LargePersonGroup.
azure_cognitiveservices_face.PersonGroup_Create({
"personGroupId": "",
"body": {}
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group. - body required MetaDataContract
- personGroupId required
Output
Output schema unknown
PersonGroupPerson_List
List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person).
azure_cognitiveservices_face.PersonGroupPerson_List({
"personGroupId": ""
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group. - start
string
: Starting person id to return (used to list a range of persons). - top
integer
: Number of persons to return starting with the person id indicated by the 'start' parameter.
- personGroupId required
Output
- output Persons
PersonGroupPerson_Create
Create a new person in a specified person group.
azure_cognitiveservices_face.PersonGroupPerson_Create({
"personGroupId": "",
"body": {}
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group. - body required NameAndUserDataContract
- personGroupId required
Output
- output Person
PersonGroupPerson_Delete
Delete an existing person from a person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted.
azure_cognitiveservices_face.PersonGroupPerson_Delete({
"personGroupId": "",
"personId": ""
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group. - personId required
string
: Id referencing a particular person.
- personGroupId required
Output
Output schema unknown
PersonGroupPerson_Get
Retrieve a person's information, including registered persisted faces, name and userData.
azure_cognitiveservices_face.PersonGroupPerson_Get({
"personGroupId": "",
"personId": ""
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group. - personId required
string
: Id referencing a particular person.
- personGroupId required
Output
- output Person
PersonGroupPerson_Update
Update name or userData of a person.
azure_cognitiveservices_face.PersonGroupPerson_Update({
"personGroupId": "",
"personId": "",
"body": {}
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group. - personId required
string
: Id referencing a particular person. - body required NameAndUserDataContract
- personGroupId required
Output
Output schema unknown
PersonGroupPerson_AddFaceFromUrl
Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until PersonGroup PersonFace - Delete, PersonGroup Person - Delete or PersonGroup - Delete is called. Note persistedFaceId is different from faceId generated by Face - Detect.
- Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
- Each person entry can hold up to 248 faces.
- JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB.
- "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from Face - Detect, there’s no guarantee to detect and add the face successfully.
- Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures.
- Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel.
- The minimum detectable face size is 36x36 pixels in an image no larger than 1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels will need a proportionally larger minimum face size.
- Different 'detectionModel' values can be provided. To use and compare different detection models, please refer to How to specify a detection model | Model | Recommended use-case(s) | | ---------- | -------- | | 'detection_01': | The default detection model for PersonGroup Person - Add Face. Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. | | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |
azure_cognitiveservices_face.PersonGroupPerson_AddFaceFromUrl({
"personGroupId": "",
"personId": "",
"ImageUrl": {
"url": ""
}
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group. - personId required
string
: Id referencing a particular person. - userData
string
: User-specified data about the face for any purpose. The maximum length is 1KB. - targetFace
array
: A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. - ImageUrl required
object
- url required
string
: Publicly reachable URL of an image
- url required
- detectionModel
string
(values: detection_01, detection_02): Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when performing Face - Detect or (Large)FaceList - Add Face or (Large)PersonGroup - Add Face. The default value is 'detection_01', if another model is needed, please explicitly specify it.
- personGroupId required
Output
- output PersistedFace
PersonGroupPerson_DeleteFace
Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId. Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel.
azure_cognitiveservices_face.PersonGroupPerson_DeleteFace({
"personGroupId": "",
"personId": "",
"persistedFaceId": ""
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group. - personId required
string
: Id referencing a particular person. - persistedFaceId required
string
: Id referencing a particular persistedFaceId of an existing face.
- personGroupId required
Output
Output schema unknown
PersonGroupPerson_GetFace
Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId).
azure_cognitiveservices_face.PersonGroupPerson_GetFace({
"personGroupId": "",
"personId": "",
"persistedFaceId": ""
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group. - personId required
string
: Id referencing a particular person. - persistedFaceId required
string
: Id referencing a particular persistedFaceId of an existing face.
- personGroupId required
Output
- output PersistedFace
PersonGroupPerson_UpdateFace
Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until PersonGroup PersonFace - Delete, PersonGroup Person - Delete or PersonGroup - Delete is called. Note persistedFaceId is different from faceId generated by Face - Detect.
- Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
- Each person entry can hold up to 248 faces.
- JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB.
- "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from Face - Detect, there’s no guarantee to detect and add the face successfully.
- Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures.
- Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel.
azure_cognitiveservices_face.PersonGroupPerson_UpdateFace({
"personGroupId": "",
"personId": "",
"persistedFaceId": "",
"body": {}
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group. - personId required
string
: Id referencing a particular person. - persistedFaceId required
string
: Id referencing a particular persistedFaceId of an existing face. - body required UpdateFaceRequest
- personGroupId required
Output
Output schema unknown
PersonGroup_Train
Queue a person group training task, the training task may not be started immediately.
azure_cognitiveservices_face.PersonGroup_Train({
"personGroupId": ""
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group.
- personGroupId required
Output
Output schema unknown
PersonGroup_GetTrainingStatus
Retrieve the training status of a person group (completed or ongoing).
azure_cognitiveservices_face.PersonGroup_GetTrainingStatus({
"personGroupId": ""
}, context)
Input
- input
object
- personGroupId required
string
: Id referencing a particular person group.
- personGroupId required
Output
- output TrainingStatus
Snapshot_List
List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take).
azure_cognitiveservices_face.Snapshot_List({}, context)
Input
- input
object
- type
string
(values: FaceList, LargeFaceList, LargePersonGroup, PersonGroup): User specified object type as a search filter. - applyScope
array
: User specified snapshot apply scopes as a search filter. ApplyScope is an array of the target Azure subscription ids for the snapshot, specified by the user who created the snapshot by Snapshot - Take.
- type
Output
- output Snapshots
Snapshot_Take
Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data. The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it