Face · Standard API · eKYC Core

Verify face video liveness

POST/v1/verify_face_video_liveness_sync

Verifies face liveness in uploaded videos and returns an is_live verdict with a liveness score, overall and per video.

Request

MethodPOST
Path/v1/verify_face_video_liveness_sync
Content-Typeapplication/json
Auth requiredYes — HMAC signing
NameTypeRequiredDescription
videos[]videoRequiredarray of video recording when liveness on SDK. Default 1
  • If you use id (result id is returned from Upload File API), omit parameter frames, metadata. If you use frames, metadata, omit parameter id.
JSON
{
    "videos": [
        {
            "id": string,
            "metadata": string_json,
            "frames": [
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                    "metadata": string_json,
                },
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                    "metadata": string_json,
                },
                // other frames
            ],
        },
        {
            "id": string,
            "metadata": string_json,
            "frames": [
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                    "metadata": string_json,
                },
                {
                    "base64": string,
                    "label": string,
                    "index": int,
                    "metadata": string_json,
                },
                // other frames
            ],
        }
    ]
}

Which each video's parameters contains:

keytyperequireddescription
idstringOptionalID of video is returned from API Upload
metadatastring_jsonOptionalkey-value string, key should be string, value should be string, int, float, bool. Example "{\"id\":\"123456789\",\"type\":1}"
frames[]FrameDataOptionallist of video frames to be uploaded

Which FrameData's parameters contains:

keytyperequireddescription
base64stringOptionalbase64 encoded text of image data
labelstringOptionallabel of the image as described at Label table
indexintOptionalthe index of this frame in the video
metadatastring_jsonOptionalkey-value string, key should be string, value should be string, int, float, bool. Example "{\"id\":\"123456789\",\"type\":1}"

Sample request

curl -X POST \
https://tv-staging.trustingsocial.com/api/v1/verify_face_video_liveness_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 \
'
{
    "videos": [
        {
            "id": "433331b5-e1d4-433f-84e6-2260ec6bee92"
        },
        {
            "id": "3b4bf7b6-088b-4931-9279-9259f5c34fe3"
        }
    ]
}
'

Response

data.is_live carries the verdict and data.score how likely it is that the face is live (0-1). 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": {
        "status": string, "success" or "failure"
        "is_live": bool, // the face is live or not
        "score": float // how likely that the face is live (0-1)
        "videos": [
            {
                "id": string, // ID of the video
                "is_live": bool, // liveness result of this video only
                "score": float // how likely that the face is live (0-1)
            },
            ... // up to 3 images
        ],
        "request_id": string // return request id to the client and can use request-id to check logs.
    },
    "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 live video comes back like this:

JSON
{
    "data": {
        "is_live": true,
        "request_id": "93029850-924c-465a-baa6-27d843cbb1ba",
        "score": 0.9999999862517992,
        "status": "success",
        "videos": [
            {
                "id": "c5c7d001-0c62-4b31-8714-3bc256a8635c",
                "is_live": true,
                "score": 1
            }
        ]
    }
}

Failure codes

If the data.status is "failure", the "errors" field will tell you why it failed.

Error codeDescription
image_has_no_facethe input image has no faces

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.
413image_too_large_exceptionThe input image size exceeds the allowed limit (15MB).
415invalid_image_format_exceptionThe provided image format is not supported (JPG/PNG)
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.
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.