Liveness Short

Description#

Liveness Detection Short is the basic version of Liveness Detection technology, which determines whether the presented image of a face is real and belongs to a living person. It is necessary for detecting fake images, such as masks/photos/videos, which can be used to bypass the authentication system or for fraudulent purposes.

This version is ideal for digital onboarding tasks and works reliably even with a weak Internet connection and on older devices.

For convenient integration via the Backend API, use Swagger (OpenAPI).

!!! info “Important” If you need a higher level of protection, we recommend using the Liveness Detection Distance or Liveness Detection PRO options, which are available when integrating via Flow Remote API.

Steps:#

1. Obtaining the organization's API KEY#

The first step in using the technology is to obtain the organization's API KEY. To obtain an organization API key, you need to go to your Personal Account at this link. The API key is located in the Backend Api Key field.

backend_api_key

Example of an organization's API key:

API KEY: Efy202XKbVAWRu...

!!! note “Note”

For clarity, a shortened length of the
`API KEY` is used. Its actual length is 47 characters or more.

2. Sending a request to determine liveliness from a photo#

Requests to our service use data in multipart/form-data format. The response data from the service will be presented in JSON format.

!!! info “Important”

To use this service, you must have a subscription. You can read more about subscriptions 
[here](../../ fundamentals/subscriptions.md).

Request URL:

https://kyc.biometric.kz/api/v1/backend/liveness/short/

Request format	Request method
multipart/form-data	POST

API KEY must be passed in the request body:

Field name	Type	Required	Description
api_key	String	Yes	API KEY of the organization in your personal account
image	File	Yes	Photo of the face

Request examples:

=== “cURL”

curl -X ‘POST’ \
‘https://kyc.biometric.kz/api/v1/backend/liveness/short/’ \
        -H ‘accept: application/json’ \
        -H ‘Content-Type: multipart/form-data’ \
        -F ‘image=@<path_to_face_photo;type=image/<image_extension>’ \
        -F ‘api_key=<organization_api_key>’
    ```

=== “Python”

    ```py
    import requests

    url = ‘https://kyc.biometric.kz/api/v1/backend/liveness/short/’
    headers = {
        ‘accept’: ‘application/json’,
    }


    face_photo_path = “<path_to_face_photo>”

    files = {
        ‘image’: (face_path_1, open(face_photo_path, ‘rb’), ‘image/<image_extension>’),
    }
    data = {
        ‘api_key’: ‘<organization_api_key>’,
    }

    response = requests.post(url, headers=headers, files=files, data=data)

    print(response.json())

    ```

=== “JavaScript”

    ```js

    /*
        dependencies to install via npm: 
        form-data, fs, node-fetch
    */

    import FormData from ‘form-data’;
    import fs from ‘fs’;
    import fetch from ‘node-fetch’;

    const face_photo_path = “<path_to_face_photo>”;

    const url = ‘https://kyc.biometric.kz/api/v1/backend/liveness/short/’;
    const apiKey = ‘<organization_api_key>’;

    const formData = new FormData();
    formData.append(‘image’, fs.createReadStream(face_photo_path));
    formData.append(‘api_key’, apiKey);

    fetch(url, {
      method: ‘POST’,
      headers: {
        ‘accept’: ‘application/json’,
      },
      body: formData
    })
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error(error));

The response will be JSON with the following fields:

backend_session_id - Session ID
result - Result of the photo liveness check
prediction - Fractional value representing the probability that the person in the photo is alive
created_at - Time when the photo liveness calculation result was created
failure_reason - Reason for failure of the face photo liveness check

Response example:

=== “Passed successfully”

```json
{
  “backend_session_id”: “f1b5887b-5f91-417a-bf04-bb45fe28cc4e”,
  “result”: true,
  “prediction”: “0.982312”,
  “created_at”: “2023-05-23T13:56:32.010Z”
  “failure_reason”: None
}
```

=== “Failed”

```json
{   
  "backend_session_id": "f1b5887b-5f91-417a-bf04-bb45fe28cc4e",
  "result": false,
  "prediction": "0.235123",
  "created_at": "2023-05-23T13:56:32.010Z"
  "failure_reason": {
       "type": "CALC_RESULT"
       "detail": "Low overall prediciton"
   }
}
```

Errors#

Код состояния	Ответ	Описание
400	Could not send image to liveness service	Can`t connect to liveness service
400	Client does not have access to Liveness technology	Client does not have access to the technology. Reasons: No subscription, or it has expired, or the technology is not active
415	Not allowed file, valid extensions: .jpg .png .jpeg	Invalid file extension, valid: .jpg .png .jpeg
400	Subscription has not started	Subscription has not been activated yet
400	No active or future subscription for technology	No active or future subscription to the technology
400	Client does not have subscription	Client does not have a subscription, you can read more about subscriptions here