Face · Standard API · eKYC Core
Search faces
Searches one or more collections for faces similar to the face in an image, and returns each match with a similarity score and the metadata indexed with it.
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 |
collection | string | Optional | search faces in this collection. If empty, the default collection will be used. case-sensitive |
collections | []string | Optional | search faces in these collections. Omit collection param if using this param. case-sensitive |
type | int | Optional | type of collection |
max_faces | int | Optional | maximum face results. Default is 10 |
special_id_type | string | Optional | id string (provided by admin) to identify special use-case. Omit this param to use the default. |
- 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.
- If you specify
collectionsnot empty, we will search in list collections. otherwise, we usecollection.
{
"image": {
"id": string,
"base64": string,
"label": string,
"metadata": string_json,
},
"collection": string,
"collections": []string,
"type": int,
"special_id_type": string,
"max_faces": int
}
Which type's parameter contains value:
| value | description |
|---|---|
3 | Matching Selfie vs Selfie |
Sample request
curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/search_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.faces holds one array of matches per face found in the input image when a single collection was searched; data.faces_in_collection holds the same, keyed by collection name, when several were. 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,
"status": string, // "success" or "failure"
"image": {
"id": string, // id of the image
"transformed_image_id": string // optional, just in case the image is transformed
},
"faces": [ // Result for single collection. support search multiple faces. Each array is result of each face
[
{
"id": string, // id of the face in image
"image_id": string, // id of original image
"score": float, // score similar between 2 faces
"metadata": [ // list of meta data information of this face
{
"field": string, // application_id, national_id, ...
"value": primitive_type, // when index key=value then the value should a primitive type as string, int, float, boolean
},
... // other fields
},
... // other face matched of first face in image
],
[
... // list face matches of another face in image
],
],
"faces_in_collection": {
"collection_name1":[ // Result for multiple collections. support search multiple faces. Each array is result of each face
[
{
"id": string, // id of the face in image
"image_id": string, // id of original image
"score": float, // score similar between 2 faces
"metadata": [ // list of meta data information of this face
{
"field": string, // application_id, national_id, ...
"value": primitive_type, // when index key=value then the value should a primitive type as string, int, float, boolean
},
... // other fields
},
... // other face matched of first face in image
],
[
... // list face matches of another face in image
],
],
"collection_name2": ... // other result on collection_name2
}
},
"errors": [
{
"code": string,
"message": string,
"detail": {
"field": string, // optional, which parameter is invalid.
... // any other information that can be useful for client
},
},
... // other errors
]
}
- The biggest faces were sorted on the top. We recommended using the first result in
facesif the input image has multiple faces.
A search of the default collection that matched two indexed faces comes back like this:
{
"data": {
"status": "success",
"image": {
"id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
},
"faces": [
[
{
"id": "e8cd85a1-e1aa-4750-a0c9-1525fb524eed",
"image_id": "91b2c846-b701-4cc2-8061-1f243c50cc52",
"score": 1,
"metadata": [
{
"field": "app_id",
"value": 3333
},
{
"field": "national_id",
"value": 4444
}
]
},
{
"id": "b05ed8b6-5d29-47a1-a934-f59f0197cea0",
"image_id": "ddb80011-c861-4904-a25f-c000cb969b61",
"score": 1,
"metadata": null
},
...
]
],
"request_id": "426bef5c-77ff-49e5-b0cd-b66651ac6427"
}
}
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 following HTTP status code with error code:
| HTTP code | Error code | Description |
|---|---|---|
401 | access_denied_exception | You are not authorized to perform the action. |
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. |
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 |
The codes above are the ones documented for this endpoint. Response errors on the Overview lists the codes for the eKYC Core surface as a whole — the two lists do not match on every endpoint.