Face · Standard API · eKYC Core
Alert faces
Retrieves suspect faces similar to the face in an image, each with a similarity score, together with the inquiry history recorded for that face.
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 you use
base64,labelandmetadata, omit parameterid. - If you use
id(resultidis returned from Upload Image API), omit parameterbase64,labelandmetadata. - If you use
embedding(resultembeddingis returned from Detect Faces API), omit parameterid,base64,labelandmetadata. - Priority order is
id, (base64,label),embedding
{
"image": {
"id": string,
"base64": string,
"label": string,
"metadata": string_json,
"embedding": []float,
},
}
Which each image's parameters contains, including the embedding this endpoint accepts:
| key | type | required | description |
|---|---|---|---|
id | string | Optional | ID of image is returned from API Upload |
base64 | string | Optional | base64 encoded text of image data |
label | string | Optional | label of the image as described at Label table |
metadata | string_json | Optional | key-value string, key should be string, value should be string, int, float, bool. Example "{\"id\":\"123456789\",\"type\":1}" |
embedding | []float | Optional | the face's vectorized from API detect faces |
Sample request
curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/alert_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 matched suspect faces per face found in the input image, and data.history the inquiry counts for that face over each time period. 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"
"faces": [ // support search multiple faces. Each array is result of each face
[
{
"name": string, // face name 1, 2, 3...
"score": float, // score similar between 2 faces
"created_at": date, // data time RFC3339 ex. 2006-01-02T15:04:05Z07:00
"applied_service": string, // kind of service that user applied
... // other fields
},
... // other face matched of first face in image
],
[
... // list face matches of another face in image
],
],
"history": [ // support history multiple faces. Each array is result of each face
[
{
"period": string, // time period as last_1day, last_7day, last_30day, last_180day
"num_suspect_faces": int, // number of matched faces in suspect DB
"num_member_suspect_faces": int, // number of members with face in suspect DB
"num_inquiry": int, // number of total inquiries made by all the member for this face
"num_member_inquiry": int, // Number of members which made the inquiry for this face in specific period
},
... // other history for other time periods
],
[
... // list history of another face in image
],
],
},
"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 face that matched one suspect, with history over four periods, comes back like this:
{
"data": {
"status": "success",
"image": {
"id": "2a5b80da-d093-4987-9711-9c7eb1b42a4d",
"faces": [
{
"bounding_box": {
"top":428,
"right":247,
"angle":0,
"bottom":521,
"left":168
},
"id": "30ae963d-d707-4528-a5ed-f3acc21f7dd7",
"landmarks": {
"left-mouth": {
"y":497.80352783203125,
"x":192.77993774414062
},
"left-eye": {
"y":460.55133056640625,
"x":189.2744140625
},
"nose": {
"y":483.4483947753906,
"x":207.6852569580078
},
"right-mouth": {
"y":497.8222961425781,
"x":222.74261474609375
},
"right-eye": {
"y":460.5907287597656,
"x":225.84567260742188
}
}
}
]
},
"faces": [
[
{
"applied_service":null,
"created_at":"2021-06-19T18:23:28.453188+00:00",
"score":0.9999999999999221,
"name":"Face 1"
}
]
],
"history": [
[
{
"num_suspect_faces":0,
"num_inquiry":1,
"num_member_suspect_faces":0,
"num_member_inquiry":1,
"period":"last_1day"
},
{
"num_suspect_faces":0,
"num_inquiry":2,
"num_member_suspect_faces":0,
"num_member_inquiry":1,
"period":"last_7day"
},
{
"num_suspect_faces":0,
"num_inquiry":3,
"num_member_suspect_faces":0,
"num_member_inquiry":1,
"period":"last_30day"
},
{
"num_suspect_faces":1,
"num_inquiry":3,
"num_member_suspect_faces":1,
"num_member_inquiry":1,
"period":"last_180day"
}
]
]
}
}
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.