face-client

name	face-client
description	Face Client API skill. Use when working with Face Client for findsimilars, group, identify. Covers 63 endpoints.
version	1.0.0
generator	lapsh

Face Client

API version: 1.0

Auth

ApiKey Ocp-Apim-Subscription-Key in header

Base URL

Not specified.

Setup

1. Set your API key in the appropriate header
2. GET /persongroups -- verify access
3. POST /findsimilars -- create first findsimilars

Endpoints

63 endpoints across 11 groups. See references/api-spec.lap for full details.

findsimilars

Method	Path	Description
POST	/findsimilars	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 With Url or Face - Detect With Stream, which will expire at the time specified by faceIdTimeToLive 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.

group

Method	Path	Description
POST	/group	Divide candidate faces into groups based on face similarity.

identify

Method	Path	Description
POST	/identify	1-to-many identification to find the closest matches of the specific query person face from a person group or large person group.

verify

Method	Path	Description
POST	/verify	Verify whether two faces belong to a same person or whether one face belongs to a person.

persongroups

Method	Path	Description
POST	/persongroups/{personGroupId}/persons	Create a new person in a specified person group.
GET	/persongroups/{personGroupId}/persons	List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person).
DELETE	/persongroups/{personGroupId}/persons/{personId}	Delete an existing person from a person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted.
GET	/persongroups/{personGroupId}/persons/{personId}	Retrieve a person's information, including registered persisted faces, name and userData.
PATCH	/persongroups/{personGroupId}/persons/{personId}	Update name or userData of a person.
DELETE	/persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}	Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId.
GET	/persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}	Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId).
PATCH	/persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}	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.
PUT	/persongroups/{personGroupId}	Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel.
DELETE	/persongroups/{personGroupId}	Delete an existing person group. Persisted face features of all people in the person group will also be deleted.
GET	/persongroups/{personGroupId}

facelists

Method	Path	Description
PUT	/facelists/{faceListId}	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.
GET	/facelists/{faceListId}	Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list.
PATCH	/facelists/{faceListId}	Update information of a face list.
DELETE	/facelists/{faceListId}	Delete a specified face list.
GET	/facelists	List face lists’ faceListId, name, userData and recognitionModel.
DELETE	/facelists/{faceListId}/persistedfaces/{persistedFaceId}	Delete a face from a face list by specified faceListId and persistedFaceId.
POST	/facelists/{faceListId}/persistedfaces	Add a face to a specified face list, up to 1,000 faces.

detect

Method	Path	Description
POST	/detect	Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.

largepersongroups

Method	Path	Description
POST	/largepersongroups/{largePersonGroupId}/persons	Create a new person in a specified large person group.
GET	/largepersongroups/{largePersonGroupId}/persons	List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person).
DELETE	/largepersongroups/{largePersonGroupId}/persons/{personId}	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.
GET	/largepersongroups/{largePersonGroupId}/persons/{personId}	Retrieve a person's name and userData, and the persisted faceIds representing the registered person face feature.
PATCH	/largepersongroups/{largePersonGroupId}/persons/{personId}	Update name or userData of a person.
DELETE	/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}	Delete a face from a person in a large person group by specified largePersonGroupId, personId and persistedFaceId.
GET	/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}	Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId).
PATCH	/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}	Update a person persisted face's userData field.
PUT	/largepersongroups/{largePersonGroupId}	Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel.
DELETE	/largepersongroups/{largePersonGroupId}	Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted.
GET	/largepersongroups/{largePersonGroupId}	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.
PATCH	/largepersongroups/{largePersonGroupId}

largefacelists

Method	Path	Description
PUT	/largefacelists/{largeFaceListId}	Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel.
GET	/largefacelists/{largeFaceListId}	Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel.
PATCH	/largefacelists/{largeFaceListId}	Update information of a large face list.
DELETE	/largefacelists/{largeFaceListId}	Delete a specified large face list.
GET	/largefacelists/{largeFaceListId}/training	Retrieve the training status of a large face list (completed or ongoing).
GET	/largefacelists	List large face lists’ information of largeFaceListId, name, userData and recognitionModel.
POST	/largefacelists/{largeFaceListId}/train	Queue a large face list training task, the training task may not be started immediately.
DELETE	/largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}	Delete a face from a large face list by specified largeFaceListId and persistedFaceId.
GET	/largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}	Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId).
PATCH	/largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}	Update a persisted face's userData field.
POST	/largefacelists/{largeFaceListId}/persistedfaces	Add a face to a specified large face list, up to 1,000,000 faces.
GET	/largefacelists/{largeFaceListId}/persistedfaces	List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face).

snapshots

Method	Path	Description
POST	/snapshots	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.
GET	/snapshots	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).
GET	/snapshots/{snapshotId}	Retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it, and target subscriptions included in the applyScope in Snapshot - Take.
PATCH	/snapshots/{snapshotId}	Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot.
DELETE	/snapshots/{snapshotId}	Delete an existing snapshot according to the snapshotId. All object data and information in the snapshot will also be deleted. Only the source subscription who took the snapshot can delete the snapshot. If the user does not delete a snapshot with this API, the snapshot will still be automatically deleted in 48 hours after creation.
POST	/snapshots/{snapshotId}/apply	Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.

operations

Method	Path	Description
GET	/operations/{operationId}	Retrieve the status of a take/apply snapshot operation.

Common Questions

Match user requests to endpoints in references/api-spec.lap. Key patterns:

• "Create a findsimilar?" -> POST /findsimilars
• "Create a group?" -> POST /group
• "Create a identify?" -> POST /identify
• "Create a verify?" -> POST /verify
• "Create a person?" -> POST /persongroups/{personGroupId}/persons
• "List all persons?" -> GET /persongroups/{personGroupId}/persons
• "Delete a person?" -> DELETE /persongroups/{personGroupId}/persons/{personId}
• "Get person details?" -> GET /persongroups/{personGroupId}/persons/{personId}
• "Partially update a person?" -> PATCH /persongroups/{personGroupId}/persons/{personId}
• "Delete a persistedface?" -> DELETE /persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}
• "Get persistedface details?" -> GET /persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}
• "Partially update a persistedface?" -> PATCH /persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}
• "Update a persongroup?" -> PUT /persongroups/{personGroupId}
• "Delete a persongroup?" -> DELETE /persongroups/{personGroupId}
• "Get persongroup details?" -> GET /persongroups/{personGroupId}
• "Partially update a persongroup?" -> PATCH /persongroups/{personGroupId}
• "List all training?" -> GET /persongroups/{personGroupId}/training
• "List all persongroups?" -> GET /persongroups
• "Create a train?" -> POST /persongroups/{personGroupId}/train
• "Update a facelist?" -> PUT /facelists/{faceListId}
• "Get facelist details?" -> GET /facelists/{faceListId}
• "Partially update a facelist?" -> PATCH /facelists/{faceListId}
• "Delete a facelist?" -> DELETE /facelists/{faceListId}
• "List all facelists?" -> GET /facelists
• "Delete a persistedface?" -> DELETE /facelists/{faceListId}/persistedfaces/{persistedFaceId}
• "Create a persistedface?" -> POST /persongroups/{personGroupId}/persons/{personId}/persistedfaces
• "Create a detect?" -> POST /detect
• "Create a persistedface?" -> POST /facelists/{faceListId}/persistedfaces
• "Create a person?" -> POST /largepersongroups/{largePersonGroupId}/persons
• "List all persons?" -> GET /largepersongroups/{largePersonGroupId}/persons
• "Delete a person?" -> DELETE /largepersongroups/{largePersonGroupId}/persons/{personId}
• "Get person details?" -> GET /largepersongroups/{largePersonGroupId}/persons/{personId}
• "Partially update a person?" -> PATCH /largepersongroups/{largePersonGroupId}/persons/{personId}
• "Delete a persistedface?" -> DELETE /largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}

Response Tips

• Check response schemas in references/api-spec.lap for field details
• Create/update endpoints typically return the created/updated object

References

• Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas

Generated from the official API spec by LAP