Face · Standard API · eKYC Core

Detect faces

POST/v1/detect_faces_sync

Detects the faces in an image and returns each one's bounding box, and its embedding vector when asked for.

Request

MethodPOST
Path/v1/detect_faces_sync
Content-Typeapplication/json
Auth requiredYes — HMAC signing

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.

NameTypeRequiredDescription
imageImageDataRequiredimage to index face. Should use image has the face
return_embeddingboolOptionalrequest to get face embedding or no
biz_idstringOptionaldetect face for any of your business requests. Please contact the administrator.
age_verificationAgeVerificationOptionalage verification request
  • If you use base64, label and metadata, omit parameter id.
  • If you use id (result id is returned from Upload Image API), omit parameter base64, label and metadata.
JSON
{
    "image": {
        "id": string,
        "base64": string,
        "label": string,
        "metadata": string_json,
    },
    "return_embedding": bool,
    "biz_id": string,
    "age_verification": {
      "age_requirement": float
    }
}

Which type's parameter contains value:

valuedescription
1Matching ID vs ID
2Matching ID vs Selfie
3Matching Selfie vs Selfie

Which AgeVerification's parameter contains value:

keytyperequireddescription
age_requirementfloatOptionalrequired minimum age for your business rule

Sample request

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/detect_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": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74"
    }
}
'

Response

data.image.faces holds one entry per detected face, each with a bounding_box and — when return_embedding was set — an embedding. 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.

JSON
{
    "data": {
        "request_id": string,
        "status": string, // "success" or "failure"
        "image": {
            "id": string,
            "transformed_image_id": string // optional, just in case the image is transformed
            "faces": [
                {
                    "id": string, // id of the face in image
                    "bounding_box": {
                        "top": int, // the top edge of the box
                        "right": int, // the right edge of the box
                        "bottom": int, // the bottom edge of the box
                        "left": int, // the left edge of the box
                        "angle": int // the angle at which the box is rotated
                    },
                    "embedding": []float, // embedding of face
                },
                ... // other faces 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
    ]
}

An image with one detected face comes back like this:

JSON
{
  "data": {
    "image": {
      "faces": [
        {
          "bounding_box": {
            "angle": 0,
            "bottom": 568,
            "left": 123,
            "right": 257,
            "top": 402
          },
          "embedding": [
            0.09560582041740417,
            -0.15577684342861176,
            -0.009643876925110817,
            -0.019479934126138687,
            0.0861940085887909,
            -0.016617512330412865,
            ...
          ],
          "id": "2cc3a440-3390-407a-914c-66a63e6eda33"
        }
      ],
      "id": "e5e32ef1-296e-4385-8f23-9eb7e6512800",
      "transformed_image_id": ""
    },
    "status": "success"
  }
}

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 codeError codeDescription
401access_denied_exceptionYou are not authorized to perform the action.
400invalid_parameter_exceptionInput parameter violates a constraint.
400request_time_too_skewedThe X-TV-Timestamp header is expired, need a newer one.
404image_not_found_exceptionThe image ID is not found in DB.
404request_not_found_exceptionThe request ID is not found when polling result by id
408request_timeout_exceptionRequest takes too long to process
429rate_limit_exceptionThe number of requests exceeded your throughput limit.
500internal_server_errorSome 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.