Face · eKYC Core
Index faces
Indexes the face in an image into a collection so it can later be retrieved by Search faces, and returns the indexed image id.
Request
Clients can provide image data to the TrustVision API by specifying the ID the image by using upload API, or by sending the image data as base64-encoded text.
| Name | Type | Required | Description |
|---|---|---|---|
image | ImageData | Required | image to index face. Should use image has the face. if use TS SDK, use last frontal image |
enable_update_metadata | bool | Optional | Allow image.metadata to be updated. |
collection | string | Optional | index faces to this collection. case-sensitive |
type | int | Optional | type of collection |
file_name | string | Optional | file name of the image, at most 255 characters. Required when file-name tracking is enabled for your client; see The file_name parameter |
- If you use
base64,labelandmetadata, omit parameterid. - If you use
id(resultidis returned from Upload Image API), omit parameterbase64,labelandmetadata. - If not set collection, default collection will be used.
{
"image": {
"id": string,
"base64": string,
"label": string,
"metadata": string_json,
},
"enable_update_metadata": bool,
"collection": string,
"type": int,
"file_name": string
}
Which type's parameter contains value:
| value | description |
|---|---|
3 | Matching Selfie vs Selfie |
The file_name parameter
file_name lets you track an indexed image by your own file name, and later delete its faces by that name with Delete faces. It is read only when TrustVision has enabled file-name tracking for your client or access key (setting require_file_name); otherwise the field is ignored. Contact your TrustVision Account Manager to enable it.
When file-name tracking is enabled:
- Every call needs a file name: the top-level
file_name, or afile_namekey insideimage.metadata. If you send both, they must be equal. The name is stored on the image asimage.metadata.file_name. file_nameis at most 255 characters. It is case-sensitive and is not trimmed. Use printable characters only — no tab, line feed, carriage return or NUL.- A file name can be live at most once for your client, across all collections. A name is live once a call indexed at least one face under it, until its faces are deleted with Delete faces. Sending a live name again is rejected with
400file_name is already indexed, before the image is uploaded. - An image in which no face is found is not tracked, so its file name stays free and can be sent again. A name whose faces were deleted can be indexed again; the image gets a new
image.id. - With
image.id(an already uploaded image), also sendenable_update_metadata: true, so the file name can be stored on the image. - A call that sends
collectionsinstead ofcollectionis not tracked by its file name: the name is not checked for duplicates, and the image cannot be deleted by name. - Do not send the same
file_namein two calls at the same time: both may pass the duplicate check.
{
"image": {
"base64": "<base64 of the image>",
"label": "portrait"
},
"file_name": "IMG_20261101_0000123.jpg",
"collection": "my_collection"
}
Sample request
curl -X POST \
'<BASE_URL>/v1/index_faces_sync' \
-H 'Authorization: TV <YOUR ACCESS KEY>:<CREATED SIGNATURE>' \
-H 'X-TV-Timestamp: 2019-04-21T18:00:15+07:00' \
-H 'Content-Type: application/json' \
-d \
'
{
"image": {
"id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
}
}
'
Response
data.image.id is the image whose face was indexed. In case the request processing has been finished, the HTTP status code will be 200, and the data.status is either "success" or "failure" depending on whether the request has been successfully processed or not.
{
"data": {
"request_id": string,
"image": {
"id": string, // id of the image
"transformed_image_id": string // optional, just in case the image is transformed
},
"status": string, // "success" or "failure"
},
"errors": [
{
"code": string,
"message": string,
"detail": {
"field": string, // optional, which parameter is invalid.
... // any other information that can be useful for client
},
},
... // other errors
]
}
A successful index comes back like this:
{
"data": {
"status": "success",
"image": {
"id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
},
"request_id": "dfdef016-e89b-4da4-ae17-5844f909c947"
}
}
Failure codes
If the data.status is "failure", the "errors" field will tell you why it failed.
In case of any other errors, the data field will be empty, and the server sends one of the following HTTP status codes with an error code:
| HTTP code | Error code | Description |
|---|---|---|
400 | invalid_parameter_exception | Input parameter violates a constraint. |
400 | request_time_too_skewed | The X-TV-Timestamp header is expired, need a newer one. |
401 | access_denied_exception | You are not authorized to perform the action. |
404 | image_not_found_exception | The image ID is not found in DB. |
404 | request_not_found_exception | The request ID is not found when polling result by id. |
408 | request_timeout_exception | Request takes too long to process. |
429 | rate_limit_exception | The number of requests exceeded your throughput limit. |
500 | internal_server_error | Some unexpected error occurs while processing the request. |
When file-name tracking is enabled for your client, file_name adds these 400 invalid_parameter_exception errors. The message is exact:
message | detail | Cause |
|---|---|---|
file_name is required | {"field": "file_name"} | Neither file_name nor image.metadata.file_name is set. |
file_name must be at most 255 characters | {"field": "file_name"} | The file name is too long. |
file_name differs from image.metadata.file_name | {"field": "file_name"} | file_name and image.metadata.file_name are both set and differ. |
image.metadata must be a JSON object to hold file_name | {"field": "image.metadata"} | file_name is set and image.metadata is not a JSON object. |
file_name with image.id requires enable_update_metadata | {"field": "file_name"} | image.id is used without enable_update_metadata: true. |
file_name is already indexed | {"field": "file_name"} | The file name is live for your client, in any collection. Nothing is stored. |
The codes above are the ones documented for this endpoint. Response errors lists the codes for the eKYC Core surface as a whole — the two lists do not match on every endpoint.