# Face Client API

> Face Client API on Apizie: 63 endpoints (Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large…, Divide candidate faces into groups based on face similarity. * The output is one or more disjointed face…, 1-to-many identification to find the closest matches of the specific query person face from a person group…, Verify whether two faces belong to a same person or whether one face belongs to a person. Remarks: * Higher…, …) returned as clean JSON through one API key. Send your own provider key in the x-upstream-key header. Call it over REST at https://apizie.tech/v1/cloud:azure-cognitiveservices-face/{endpoint} or from Claude, ChatGPT and Cursor through the Apizie MCP server. Free plan: 1,000 requests a month.

- Project key: `cloud:azure-cognitiveservices-face`
- Category: Cloud
- Status: byok
- Source: https://learn.microsoft.com/rest/api/azure/
- Page: https://apizie.tech/api/cloud/azure-cognitiveservices-face
- OpenAPI: https://apizie.tech/api/cloud/azure-cognitiveservices-face/openapi.json

An API for face detection, verification, and identification.

## Endpoints

### Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-find-similar` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| body | object | yes | JSON request body |

### Divide candidate faces into groups based on face similarity. * The output is one or more disjointed face…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-group` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| body | object | yes | JSON request body |

### 1-to-many identification to find the closest matches of the specific query person face from a person group…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-identify` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| body | object | yes | JSON request body |

### Verify whether two faces belong to a same person or whether one face belongs to a person. Remarks: * Higher…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-verify-face-to-face` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| body | object | yes | JSON request body |

### List all persons in a person group, and retrieve person information (including personId, name, userData and…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-person-list` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |
| start | string | no | Starting person id to return (used to list a range of persons). |
| top | integer | no | Number of persons to return starting with the person id indicated by the 'start' parameter. |

### Create a new person in a specified person group.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-person-create` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |
| body | object | yes | JSON request body |

### Retrieve a person's information, including registered persisted faces, name and userData.
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-person-get` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |
| personId | string | yes | Id referencing a particular person. |

### Update name or userData of a person.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-person-update` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |
| personId | string | yes | Id referencing a particular person. |
| body | object | yes | JSON request body |

### Delete an existing person from a person group. The persistedFaceId, userData, person name and face feature…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-person-delete` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |
| personId | string | yes | Id referencing a particular person. |

### Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-person-get-face` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |
| personId | string | yes | Id referencing a particular person. |
| persistedFaceId | string | yes | Id referencing a particular persistedFaceId of an existing face. |

### Add a face to a person into a person group for face identification or verification. To deal with an image…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-person-update-face` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |
| personId | string | yes | Id referencing a particular person. |
| persistedFaceId | string | yes | Id referencing a particular persistedFaceId of an existing face. |
| body | object | yes | JSON request body |

### Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId.…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-person-delete-face` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |
| personId | string | yes | Id referencing a particular person. |
| persistedFaceId | string | yes | Id referencing a particular persistedFaceId of an existing face. |

### Retrieve person group name, userData and recognitionModel. To get person information under this personGroup,…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-get` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |
| returnRecognitionModel | boolean | no | A value indicating whether the operation should return 'recognitionModel' in response. |

### Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. A…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-create` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |
| body | object | yes | JSON request body |

### Update an existing person group's display name and userData. The properties which does not appear in request…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-update` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |
| body | object | yes | JSON request body |

### Delete an existing person group. Persisted face features of all people in the person group will also be…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-delete` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |

### Retrieve the training status of a person group (completed or ongoing).
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-get-training-status` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |

### List person groups’ personGroupId, name, userData and recognitionModel. * Person groups are stored in…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-list` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| start | string | no | List person groups from the least personGroupId greater than the "start". |
| top | integer | no | The number of person groups to list. |
| returnRecognitionModel | boolean | no | A value indicating whether the operation should return 'recognitionModel' in response. |

### Queue a person group training task, the training task may not be started immediately.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-train` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |

### Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list.
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-list-get` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| faceListId | string | yes | Id referencing a particular face list. |
| returnRecognitionModel | boolean | no | A value indicating whether the operation should return 'recognitionModel' in response. |

### Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel.…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-list-create` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| faceListId | string | yes | Id referencing a particular face list. |
| body | object | yes | JSON request body |

### Update information of a face list.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-list-update` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| faceListId | string | yes | Id referencing a particular face list. |
| body | object | yes | JSON request body |

### Delete a specified face list.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-list-delete` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| faceListId | string | yes | Id referencing a particular face list. |

### List face lists’ faceListId, name, userData and recognitionModel. To get face information inside faceList…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-list-list` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| returnRecognitionModel | boolean | no | A value indicating whether the operation should return 'recognitionModel' in response. |

### Delete a face from a face list by specified faceListId and persistedFaceId. Adding/deleting faces to/from a…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-list-delete-face` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| faceListId | string | yes | Id referencing a particular face list. |
| persistedFaceId | string | yes | Id referencing a particular persistedFaceId of an existing face. |

### Add a face to a person into a person group for face identification or verification. To deal with an image…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/person-group-person-add-face-from-url` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| personGroupId | string | yes | Id referencing a particular person group. |
| personId | string | yes | Id referencing a particular person. |
| userData | string | no | User-specified data about the face for any purpose. The maximum length is 1KB. |
| targetFace | array | no | 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.… |
| detectionModel | string | no | Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when… |

### Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-detect-with-url` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| returnFaceId | boolean | no | A value indicating whether the operation should return faceIds of detected faces. Detecting with this value set to true requires… |
| returnFaceLandmarks | boolean | no | A value indicating whether the operation should return landmarks of the detected faces. |
| returnFaceAttributes | array | no | Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". The… |
| recognitionModel | string | no | Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds,… |
| returnRecognitionModel | boolean | no | A value indicating whether the operation should return 'recognitionModel' in response. |
| detectionModel | string | no | Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when… |
| faceIdTimeToLive | integer | no | The number of seconds for the faceId being cached. Supported range from 60 seconds up to 86400 seconds. The default value is 86400 (24… |

### Add a face to a specified face list, up to 1,000 faces. To deal with an image contains multiple faces, input…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-list-add-face-from-url` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| faceListId | string | yes | Id referencing a particular face list. |
| userData | string | no | User-specified data about the face for any purpose. The maximum length is 1KB. |
| targetFace | array | no | 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.… |
| detectionModel | string | no | Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when… |

### List all persons in a large person group, and retrieve person information (including personId, name,…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-person-list` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |
| start | string | no | Starting person id to return (used to list a range of persons). |
| top | integer | no | Number of persons to return starting with the person id indicated by the 'start' parameter. |

### Create a new person in a specified large person group.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-person-create` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |
| body | object | yes | JSON request body |

### Retrieve a person's name and userData, and the persisted faceIds representing the registered person face…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-person-get` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |
| personId | string | yes | Id referencing a particular person. |

### Update name or userData of a person.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-person-update` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |
| personId | string | yes | Id referencing a particular person. |
| body | object | yes | JSON request body |

### Delete an existing person from a large person group. The persistedFaceId, userData, person name and face…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-person-delete` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |
| personId | string | yes | Id referencing a particular person. |

### Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-person-get-face` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |
| personId | string | yes | Id referencing a particular person. |
| persistedFaceId | string | yes | Id referencing a particular persistedFaceId of an existing face. |

### Update a person persisted face's userData field.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-person-update-face` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |
| personId | string | yes | Id referencing a particular person. |
| persistedFaceId | string | yes | Id referencing a particular persistedFaceId of an existing face. |
| body | object | yes | JSON request body |

### Delete a face from a person in a large person group by specified largePersonGroupId, personId and…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-person-delete-face` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |
| personId | string | yes | Id referencing a particular person. |
| persistedFaceId | string | yes | Id referencing a particular persistedFaceId of an existing face. |

### Retrieve the information of a large person group, including its name, userData and recognitionModel. This…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-get` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |
| returnRecognitionModel | boolean | no | A value indicating whether the operation should return 'recognitionModel' in response. |

### Create a new large person group with user-specified largePersonGroupId, name, an optional userData and…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-create` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |
| body | object | yes | JSON request body |

### Update an existing large person group's display name and userData. The properties which does not appear in…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-update` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |
| body | object | yes | JSON request body |

### Delete an existing large person group. Persisted face features of all people in the large person group will…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-delete` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |

### Retrieve the training status of a large person group (completed or ongoing).
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-get-training-status` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |

### List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel. * Large…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-list` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| start | string | no | List large person groups from the least largePersonGroupId greater than the "start". |
| top | integer | no | The number of large person groups to list. |
| returnRecognitionModel | boolean | no | A value indicating whether the operation should return 'recognitionModel' in response. |

### Queue a large person group training task, the training task may not be started immediately.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-train` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |

### Add a face to a person into a large person group for face identification or verification. To deal with an…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-person-group-person-add-face-from-url` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largePersonGroupId | string | yes | Id referencing a particular large person group. |
| personId | string | yes | Id referencing a particular person. |
| userData | string | no | User-specified data about the face for any purpose. The maximum length is 1KB. |
| targetFace | array | no | 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.… |
| detectionModel | string | no | Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when… |

### Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel.
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-face-list-get` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largeFaceListId | string | yes | Id referencing a particular large face list. |
| returnRecognitionModel | boolean | no | A value indicating whether the operation should return 'recognitionModel' in response. |

### Create an empty large face list with user-specified largeFaceListId, name, an optional userData and…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-face-list-create` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largeFaceListId | string | yes | Id referencing a particular large face list. |
| body | object | yes | JSON request body |

### Update information of a large face list.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-face-list-update` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largeFaceListId | string | yes | Id referencing a particular large face list. |
| body | object | yes | JSON request body |

### Delete a specified large face list.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-face-list-delete` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largeFaceListId | string | yes | Id referencing a particular large face list. |

### Retrieve the training status of a large face list (completed or ongoing).
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-face-list-get-training-status` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largeFaceListId | string | yes | Id referencing a particular large face list. |

### List large face lists’ information of largeFaceListId, name, userData and recognitionModel. To get face…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-face-list-list` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| returnRecognitionModel | boolean | no | A value indicating whether the operation should return 'recognitionModel' in response. |
| start | string | no | Starting large face list id to return (used to list a range of large face lists). |
| top | integer | no | Number of large face lists to return starting with the large face list id indicated by the 'start' parameter. |

### Queue a large face list training task, the training task may not be started immediately.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-face-list-train` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largeFaceListId | string | yes | Id referencing a particular large face list. |

### Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId).
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-face-list-get-face` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largeFaceListId | string | yes | Id referencing a particular large face list. |
| persistedFaceId | string | yes | Id referencing a particular persistedFaceId of an existing face. |

### Update a persisted face's userData field.
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-face-list-update-face` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largeFaceListId | string | yes | Id referencing a particular large face list. |
| persistedFaceId | string | yes | Id referencing a particular persistedFaceId of an existing face. |
| body | object | yes | JSON request body |

### Delete a face from a large face list by specified largeFaceListId and persistedFaceId. Adding/deleting faces…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-face-list-delete-face` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largeFaceListId | string | yes | Id referencing a particular large face list. |
| persistedFaceId | string | yes | Id referencing a particular persistedFaceId of an existing face. |

### List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-face-list-list-faces` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largeFaceListId | string | yes | Id referencing a particular large face list. |
| start | string | no | Starting face id to return (used to list a range of faces). |
| top | integer | no | Number of faces to return starting with the face id indicated by the 'start' parameter. |

### Add a face to a specified large face list, up to 1,000,000 faces. To deal with an image contains multiple…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/large-face-list-add-face-from-url` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| largeFaceListId | string | yes | Id referencing a particular large face list. |
| userData | string | no | User-specified data about the face for any purpose. The maximum length is 1KB. |
| targetFace | array | no | 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.… |
| detectionModel | string | no | Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when… |

### List all accessible snapshots with related information, including snapshots that were taken by the user, or…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/snapshot-list` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| type | string | no | User specified object type as a search filter. |
| applyScope | array | no | User specified snapshot apply scopes as a search filter. ApplyScope is an array of the target Azure subscription ids for the snapshot,… |

### Submit an operation to take a snapshot of face list, large face list, person group or large person group,…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/snapshot-take` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| body | object | yes | JSON request body |

### Retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it,…
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/snapshot-get` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| snapshotId | string | yes | Id referencing a particular snapshot. |

### Update the information of a snapshot. Only the source subscription who took the snapshot can update the…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/snapshot-update` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| snapshotId | string | yes | Id referencing a particular snapshot. |
| body | object | yes | JSON request body |

### Delete an existing snapshot according to the snapshotId. All object data and information in the snapshot…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/snapshot-delete` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| snapshotId | string | yes | Id referencing a particular snapshot. |

### Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions…
`POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/snapshot-apply` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| snapshotId | string | yes | Id referencing a particular snapshot. |
| body | object | yes | JSON request body |

### Retrieve the status of a take/apply snapshot operation.
`GET https://apizie.tech/v1/cloud:azure-cognitiveservices-face/snapshot-get-operation-status` (byok)

| Parameter | Type | Required | Description |
|---|---|---|---|
| Endpoint | string | yes | Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). |
| operationId | string | yes | Id referencing a particular take/apply snapshot operation. |

## Example
```
curl "https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-find-similar" \
  -H "x-api-key: $APIZIE_KEY" \
  -H "x-upstream-key: $PROVIDER_KEY"
```

## FAQ

### How do I call the Face Client API?
Create a free Apizie key, then send POST https://apizie.tech/v1/cloud:azure-cognitiveservices-face/face-find-similar with the header x-api-key. Every endpoint returns { project, data, timestamp }.

### Is the Face Client API free on Apizie?
Yes. The Free plan includes 1,000 requests a month at 100 requests a minute, no credit card. Face Client itself also needs your own key from azure.com.

### Can AI agents use the Face Client API?
Yes. Add the Apizie MCP server (https://apizie.tech/mcp) to Claude, ChatGPT, Cursor or VS Code, then ask in plain language. The agent calls run_scraper with project key cloud:azure-cognitiveservices-face.

### What is the status of the Face Client API?
Needs your own provider key (bring your own key)