Face · eKYC Core
Delete faces
Deletes the given image ids out of a face collection's index and returns the id of the request.
Request
| Name | Type | Required | Description |
|---|---|---|---|
image_ids | []string | Required | image IDs in DB. Should use indexed image. Omit when you send file_names |
collection | string | Optional | index faces to this collection |
file_names | []string | Optional | file names the images were indexed with, 1 to 100. Only with file-name tracking; see The file_names parameter |
- If not set collection, default collection will be used.
{
"image_ids": []string,
"collection": string,
"file_names": []string,
}
The file_names parameter
file_names deletes faces by the file_name they were indexed with in Index faces, instead of by image ID. It is read only when TrustVision has enabled file-name tracking for your client or access key (setting require_file_name); otherwise image_ids stays required.
- Send 1 to 100 names, none of them empty. Names are matched exactly as they were indexed.
- Send
file_namesorimage_ids, never both. Deleting byimage_idsworks as before. - Names are looked up in
collectiononly (the default collection if it is not set). - The response lists in
data.unknown_file_namesthe names that are not live in the collection: never indexed, indexed without a face, already deleted, or indexed in another collection. Every other name was found, and its faces are deleted. If no name is found, the call fails with400no image found for file_names. - Once its faces are deleted, a file name is free again and can be indexed with a new image.
{
"file_names": ["IMG_20261101_0000123.jpg", "IMG_20261101_0000124.jpg"],
"collection": "my_collection"
}
Sample request
curl -X POST \
'<BASE_URL>/v1/delete_faces' \
-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_ids": [
"a4facba3-334b-41fb-97e3-4766cb70ae29",
"7db00808-0416-45cf-a5cb-3b6dfbd7bb74"
]
}
'
Response
In case of success, the HTTP status code will be 200, and the data will be an object containing following fields:
| field | type | description |
|---|---|---|
status | string | "success" |
request_id | string | ID of the request (UUID) |
unknown_file_names | []string | only when deleting by file_names: the names not found in the collection, [] if all were found |
{
"data": {
"status": string,
"request_id": string,
"unknown_file_names": []string, // only when deleting by file_names
},
"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 delete comes back like this:
{
"data": {
"status": "success",
"request_id": "d4493ff5-e41f-4d10-a291-6a9727050b4c"
}
}
A delete by file_names in which one name was not found:
{
"data": {
"status": "success",
"request_id": "d4493ff5-e41f-4d10-a291-6a9727050b4c",
"unknown_file_names": ["IMG_20261101_0000124.jpg"]
}
}
Failure codes
In case of error, the data 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. |
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 deleting by file_names, these 400 invalid_parameter_exception errors can occur. The message is exact:
message | detail | Cause |
|---|---|---|
no image found for file_names | {"field": "file_names"} | No name of the call is live in the collection. Nothing is deleted. |
image_ids and file_names cannot be used together | {"field": "file_names"} | Both image_ids and file_names are set. |
file_names cannot contain an empty name | {"field": "file_names"} | file_names holds "". |
number faces delete must be less than 100 | none | More than 100 names. 100 is accepted. |
parameter is required | {"field": "image_ids"} | Neither image_ids nor file_names is set, or file-name tracking is off. |
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.