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.
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 |