1 of 1

Методы API Lite

Начиная с версии 1.1.0, Oz API Lite может принимать изображения и шаблоны в формате base64, а также возвращать в этом формате шаблоны биометрических проверок. Для включения этой опции необходимо в headers запроса передать Content-Transfer-Encoding = base64.

version – проверка версии компонентов

С помощью этого метода можно узнать, какие версии компонентов используются (начиная с версии 1.1.1).

Call GET /version

Входные параметры

Пример запроса

GET localhost/version

Успешный ответ метода

В случае успешного ответа метод возвращает сообщение со следующими параметрами.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

core

String

Версия API Lite.

tfss

String

Версия TFSS.

models

[String]

Массив версий моделей, где каждая запись содержит информацию о названии модели и ее версии.

Пример ответа

200 OK
Content-Type: application/json
{
2	"core": "core_version",
3	"tfss": "tfss_version",
4	"models": [
5		{
6			"name": "model_name",
7			"version": "model_version"
8		}
9	]
10}

Биометрия

health – проверка состояния биометрического процессора biometry

С помощью этого метода можно проверить, корректно ли работает процессор.

Вызов метода: GET /v1/face/pattern/health

Входные параметры

Пример запроса

GET localhost/v1/face/pattern/health

Успешный ответ метода

В случае успешного ответа метод возвращает сообщение со следующими параметрами.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

status

Int

0 – биометрический процессор работает корректно.

3 – биометрический процессор неработоспособен.

message

String

Сообщение.

Пример ответа

200 OK
Content-Type: application/json
{“status”: 0, message: “”}

extract – извлечение биометрического шаблона

Метод предназначен для извлечения биометрического шаблона из изображения. Тип контента HTTP-запроса: “image/jpeg” или “image/png”

Вызов метода: POST /v1/face/pattern/extract

Входные параметры

Наименование параметра

Тип

Описание

Не указывается*

Stream

Обязательный параметр. Изображение для извлечения биометрического шаблона. В заголовочном поле “Content-Type” должен быть указан тип контента.

Для параметров типа Stream имя указывать не нужно.

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/extract
Content-Type: image/jpeg
{Поток байт изображения}

Успешный ответ метода

В случае успешного ответа метод возвращает биометрический шаблон.

Тип контента HTTP-ответа: “application/octet-stream”.

Если в headers запроса передавалось поле Content-Transfer-Encoding со значением base64, то шаблон тоже вернется в base64.

Выходные параметры

Наименование параметра

Тип

Описание

Не указывается*

Stream

Биометрический шаблон, полученный из изображения

Для параметров типа Stream имя указывать не нужно.

Пример ответа

200 OK
Content-Type: application/octet-stream
{Поток байт биометрического шаблона}

compare – сравнение биометрических шаблонов

Метод предназначен для сравнения двух биометрических шаблонов.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/compare

Входные параметры

Наименование параметра

Тип

Описание

bio_feature

Stream

Обязательный параметр. Первый биометрический шаблон.

bio_template

Stream

Обязательный параметр. Второй биометрический шаблон.

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/compare
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”bio_feature”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”bio_template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результат сравнения двух шаблонов.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

score

Float

Результат сравнения двух шаблонов

decision

String

Рекомендуемое решение по полученному score.

approved – положительный результат. Лица совпадают.

operator_required – требуется дополнительная проверка оператора.

declined – негативный результат. Лица не совпадают.

Пример ответа

200 OK
Content-Type: application/json
{“score”: 1.0, “decision”: “approved”}

verify – биометрическая верификация

Метод объединяет два описанных выше метода extract и compare – извлекает биометрический шаблон из изображения и сравнивает его с другим биометрическим шаблоном, который также передается в запросе.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/verify

Входные параметры

Наименование параметра

Тип

Описание

sample

Stream

Обязательный параметр. Изображение для извлечения биометрического шаблона.

bio_template

Stream

Обязательный параметр. Биометрический шаблон, с которым производится сравнение.

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/verify
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”bio_template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”sample”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результат сравнения двух биометрических шаблонов.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

score

Float

Результат сравнения двух шаблонов

decision

String

Рекомендуемое решение по полученному score.

approved – положительный результат. Лица совпадают.

operator_required – требуется дополнительная проверка оператора.

declined – негативный результат. Лица не совпадают.

Пример ответа

200 OK
Content-Type: application/json
{“score”: 1.0, “decision”: “approved”}

extract_and_compare – извлечение из двух изображений и сравнение полученных шаблонов

Метод объединяет два описанных выше метода extract и compare. Он извлекает биометрические шаблоны из двух изображений, сравнивает их и в качестве ответа передает результат сравнения.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/extract_and_compare

Входные параметры

Наименование параметра

Тип

Описание

sample_1

Stream

Обязательный параметр. Первое изображение.

sample_2

Stream

Обязательный параметр. Второе изображение

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/extract_and_compare
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”sample_1”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”sample_2”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результат сравнения двух извлеченных биометрических шаблонов.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

score

Float

Результат сравнения двух извлеченных шаблонов

decision

String

Рекомендуемое решение по полученному score.

approved – положительный результат. Лица совпадают.

operator_required – требуется дополнительная проверка оператора.

declined – негативный результат. Лица не совпадают.

Пример ответа

200 OK
Content-Type: application/json
{“score”: 1.0, “decision”: “approved”}

compare_n – сравнение биометрических шаблонов 1:N

Метод предназначен для сравнения биометрических шаблонов в режиме 1:N.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/compare_n

Входные параметры

Наименование параметра

Тип

Описание

template_1

Stream

Обязательный параметр.

Биометрический шаблон – кандидат(1).

templates_n

Stream

Обязательный параметр.

Список(N) биометрических шаблонов. Каждый биометрический шаблон должен быть передан отдельно, но необходимо чтобы имя параметра было templates_n. Также требуется, чтобы в заголовке был передан filename.

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/compare_n
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”template_1”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”1.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”2.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”3.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результаты сравнений 1:N .

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

results

List[JSON]

Список результатов сравнения кандидата со списком(N). Для каждого сравнения из списка(N) результат имеет следующие поля:

*filename

String

Значение filename в заголовке соответствующего шаблона из списка(N).

*score

Float

Результат сравнения кандидата с соответствующим шаблоном из списка(N).

*decision

String

Рекомендуемое решение по полученному score.

approved - положительный результат. Лица совпадают.

operator_required - требуется дополнительная проверка оператора.

declined - негативный результат. Лица не совпадают.

Пример ответа

200 OK
Content-Type: application/json
{'results': [
    {'filename': '1.template', 'score': 0.0, 'decision': 'declined'}, 
    {'filename': '2.template', 'score': 1.0, 'decision': 'approved'}, 
    {'filename': '3.template', 'score': 0.21, 'decision': 'declined'}
]}

verify_n – биометрическая верификация 1:N

Метод объединяет два описанных выше метода extract и compare_n. Метод извлекает биометрический шаблон из изображения и сравнивает его cо списком биометрических шаблонов, которые также передаются в запросе.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/verify_n

Входные параметры

Наименование параметра

Тип

Описание

sample_1

Stream

Обязательный параметр.

Изображение - кандидат(1).

templates_n

Stream

Обязательный параметр.

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/verify_n
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”sample_1”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”1.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”2.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”3.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результаты сравнений 1:N .

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

results

List[JSON]

*filename

String

Значение filename в заголовке соответствующего шаблона из списка(N).

*score

Float

Результат сравнения кандидата с соответствующим шаблоном из списка(N).

*decision

String

Рекомендуемое решение по полученному score.

approved - положительный результат. Лица совпадают.

operator_required - требуется дополнительная проверка оператора.

declined - негативный результат. Лица не совпадают.

Пример ответа

200 OK
Content-Type: application/json
{'results': [
    {'filename': '1.template', 'score': 0.0, 'decision': 'declined'}, 
    {'filename': '2.template', 'score': 1.0, 'decision': 'approved'}, 
    {'filename': '3.template', 'score': 0.21, 'decision': 'declined'}
]}

extract_and_compare_n – извлечение и сравнение полученных шаблонов 1:N

Метод объединяет два описанных выше метода extract и compare_n. Он извлекает биометрические шаблоны из изображения-кандидата и изображений из списка, а затем сравнивает их в режиме 1:N.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/extract_and_compare_n

Входные параметры

Наименование параметра

Тип

Описание

sample_1

Stream

Обязательный параметр.

Изображение – кандидат(1).

samples_n

Stream

Обязательный параметр.

Список(N) изображений. Каждое изображение должно быть передано отдельно, но необходимо чтобы имя параметра было samples_n. Также требуется, чтобы в заголовке был передан filename.

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/extract_and_compare_n
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”sample_1”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”samples_n”; filename=”1.jpeg”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”samples_n”; filename=”2.jpeg”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”samples_n”; filename=”3.jpeg”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результаты сравнений 1:N .

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

results

List[JSON]

*filename

String

Значение filename в заголовке соответствующего изображения из списка(N).

*score

Float

Результат сравнения кандидата с соответствующим изображением из списка(N).

*decision

String

Рекомендуемое решение по полученному score.

approved – положительный результат. Лица совпадают.

operator_required – требуется дополнительная проверка оператора.

declined – негативный результат. Лица не совпадают.

Пример ответа

200 OK
Content-Type: application/json
{'results': [
    {'filename': '1.jpeg', 'score': 0.0, 'decision': 'declined'}, 
    {'filename': '2.jpeg', 'score': 1.0, 'decision': 'approved'}, 
    {'filename': '3.jpeg', 'score': 0.21, 'decision': 'declined'}
]}

Ошибки методов

Тип контента HTTP-ответа: “application/json”.

Коды ответов HTTP

Значение параметра “code”

Описание

400

BPE-002001

Неверный Content-Type HTTP-запроса

400

BPE-002002

Неверный метод HTTP-запроса

400

BPE-002003

Не удалось прочитать *биометрический образец

400

BPE-002004

Не удалось прочитать биометрический шаблон

400

BPE-002005

Неверный Content-Type части multiparted HTTPзапроса

400

BPE-003001

Не удалось извлечь биометрический шаблон

400

BPE-003002

На биометрическом образце* отсутствует лицо

400

BPE-003003

На биометрическом образце* присутствует более одного лица

500

BPE-001001

Внутренняя ошибка биопроцессора

400

BPE-001002

Ошибка TFSS. Необходимо вызвать метод biometry health.

Биометрический образец – входное изображение.

Liveness

health – проверка состояния биометрического процессора liveness

Вызов метода: GET /v1/face/liveness/health

Входные параметры отсутствуют.

Пример запроса

GET localhost/v1/face/liveness/health

Успешный ответ метода

В случае успешного ответа метод возвращает сообщение со следующими параметрами.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

status

Int

0 - биометрический процессор работает корректно.

3 - биометрический процессор неработоспособен.

message

String

Сообщение.

Пример ответа

200 OK
Content-Type: application/json
{“status”: 0, message: “”}

detect – обнаружение презентационных атак

Метод detect предназначен для обнаружения презентационных атак. Он ищет лицо на каждом изображении или видео (с версии 1.2.0), отправляет найденные лица на анализ и возвращает результат.

Поддерживаются следующие Content-Type:

image/jpeg или image/png для изображения;
multipart/form-data для изображений, видео или архивов. Для добавления дополнительных параметров, влияющих на анализ, используйте payload.

Запуск метода:POST /{version}/face/liveness/detect.

Изображение

Принимает изображение в формате JPEG или PNG; без payload.

Пример запроса

POST /v1/face/liveness/detect HTTP/1.1
Host: localhost
Content-Type: image/jpeg
Content-Length: [длина тела сообщения]
[поток байт изображения]

Пример успешного ответа

HTTP/1.1 200 OK
Content-Type: application/json
{
  "passed": false,
  "score": 0.999484062
}

Multipart/form-data

Принимает запрос multipart/form-data.

Название каждого медиафайла должно быть уникальным, например, media_key1, media_key2.
Параметры payload должны быть в виде JSON, помещенного в поле payload.

Временные идентификаторы будут удалены после выполнения запроса.

Пример запроса

POST /v1/face/liveness/detect HTTP/1.1
Host: localhost
Content-Length: [длина тела сообщения]
Content-Type: multipart/form-data; boundary=--BOUNDARY--

--BOUNDARY--
Content-Disposition: form-data; name="media_key1"; filename="video.mp4"
Content-Type: multipart/form-data; 

[поток байт медиафайла]
--BOUNDARY--
Content-Disposition: form-data; name="payload"

    {
        "folder:meta_data": {
            "partner_side_folder_id": "partner_side_folder_id_if_needed",
            "person_info": {
                "first_name": "John",
                "middle_name": "Jameson",
                "last_name": "Doe"
            }
        },
        "resolution_endpoint": "https://www.your-custom-endpoint.com",
        "media:meta_data": {
            "media_key1": {
                "foo": "bar2"
            }
        },
        "media:tags": {
            "media_key1": [
                "video_selfie",
                "video_selfie_blank"
            ]
        },
        "analyses": [
          {
            "type": "quality",
            "meta_data": {
              "example1": "some_example1"
            },
            "params": {
                "threshold_spoofing": 0.6,
                "extract_best_shot": false
            }
          }
]
    }
--BOUNDARY--

Пример успешного ответа

{
    "company_id": null,
    "time_created": 1720180784.769608,
    "folder_id": "folder_id", // временный ID
    "user_id": null,
    "resolution_endpoint": "https://www.your-custom-endpoint.com",
    "resolution_status": "FINISHED",
    "resolution_comment": "[]",
    "system_resolution": "SUCCESS",
    "resolution_time": null,
    "resolution_author_id": null,
    "resolution_state_hash": null,
    "operator_comment": null,
    "operator_status": null,
    "is_cleared": null,
    "meta_data": {
        "partner_side_folder_id": "partner_side_folder_id_if_needed",
        "person_info": {
            "first_name": "John",
            "middle_name": "Jameson",
            "last_name": "Doe"
        }
    },
    "technical_meta_data": {},
    "time_updated": 1720180787.531983,
    "media": [
        {
            "folder_id": "folder_id", // временный ID
            "media_id": "video_id", // временный ID
            "media_type": "VIDEO_FOLDER",
            "info": {
                "thumb": null,
                "video": {
                    "duration": 3.76,
                    "FPS": 22.83,
                    "width": 960,
                    "height": 720,
                    "md5": "8879b4fa9ee7add77aceb8d7d5d7b92d",
                    "size": 6017119,
                    "mime-type": "video/mp4"
                }
            },
            "tags": [
                "video_selfie",
                "video_selfie_blank",
                "orientation_portrait"
            ],
            "original_name": "video-5mb.mp4",
            "original_url": null,
            "company_id": null,
            "technical_meta_data": {},
            "time_created": 1719573752.78253,
            "time_updated": 1720180787.531801,
            "meta_data": {
                "foo4": "bar5"
            },
            "thumb_url": null,
            "folder_time_created": null,
            "video_id": "video_id", // временный ID
            "video_url": null
        }
    ],
    "analyses": [
        {
            "analyse_id": null,
            "analysis_id": null,
            "folder_id": "folder_id", // временный ID
            "folder_time_created": null,
            "type": "QUALITY",
            "state": "FINISHED",
            "company_id": null,
            "group_id": null,
            "results_data": null,
            "confs": {
                "threshold_replay": 0.5,
                "extract_best_shot": false,
                "threshold_liveness": 0.5,
                "threshold_spoofing": 0.42
            },
            "error_message": null,
            "error_code": null,
            "resolution_operator": null,
            "technical_meta_data": {},
            "time_created": 1720180784.769944,
            "time_updated": 1720180787.531877,
            "meta_data": {
                "some_key": "some_value"
            },
            "source_media": [
                {
                    "folder_id": "folder_id", // временный ID
                    "media_id": "video_id", // временный ID
                    "media_type": "VIDEO_FOLDER",
                    "info": {
                        "thumb": null,
                        "video": {
                            "duration": 3.76,
                            "FPS": 22.83,
                            "width": 960,
                            "height": 720,
                            "md5": "8879b4fa9ee7add77aceb8d7d5d7b92d",
                            "size": 6017119,
                            "mime-type": "video/mp4"
                        }
                    },
                    "tags": [
                        "video_selfie",
                        "video_selfie_blank",
                        "orientation_portrait"
                    ],
                    "original_name": "video-5mb.mp4",
                    "original_url": null,
                    "company_id": null,
                    "technical_meta_data": {},
                    "time_created": 1719573752.78253,
                    "time_updated": 1720180787.531801,
                    "meta_data": {
                        "foo4": "bar5"
                    },
                    "thumb_url": null,
                    "folder_time_created": null,
                    "video_id": "video_id", // временный ID
                    "video_url": null
                }
            ],
            "results_media": [
                {
                    "company_id": null,
                    "media_association_id": "video_id", // временный ID
                    "analysis_id": null,
                    "results_data": {
                        "confidence_spoofing": 0.000541269779
                    },
                    "source_media_id": "video_id", // временный ID
                    "output_images": [],
                    "collection_persons": [],
                    "folder_time_created": null
                }
            ],
            "resolution_status": "SUCCESS",
            "resolution": "SUCCESS"
        }
    ]
}

Multipart/form-data с Best Shot

Для извлечения лучшего кадра укажите в блоке analyses в payload extract_best_shot = true (как в примере запроса ниже). В таком случае API Lite после анализа ваших медиафайлов вернет в ответе лучший кадр – изображение в base64 будет в analysis->output_images->image_b64. Лучший кадр можно извлекать только из видео или архивов.

Также в блоке analyses вы можете изменить порог для прохождения Liveness в параметре threshold_spoofing: если итоговая оценка выше значения этого параметра, результат анализа будет DECLINED, в ином случае проверка Liveness будет считаться пройденной.

Пример запроса

POST /v1/face/liveness/detect HTTP/1.1
Host: localhost
Content-Length: [длина тела сообщения]
Content-Type: multipart/form-data; boundary=--BOUNDARY--

--BOUNDARY--
Content-Disposition: form-data; name="media_key1"; filename="video.mp4"
Content-Type: multipart/form-data; 

[поток байт медиафайла]
--BOUNDARY--
Content-Disposition: form-data; name="payload"

    {
        "folder:meta_data": {
            "partner_side_folder_id": "partner_side_folder_id_if_needed",
            "person_info": {
                "first_name": "John",
                "middle_name": "Jameson",
                "last_name": "Doe"
            }
        },
        "resolution_endpoint": "https://www.your-custom-endpoint.com",
        "media:meta_data": {
            "media_key1": {
                "foo": "bar2"
            }
        },
        "media:tags": {
            "media_key1": [
                "video_selfie",
                "video_selfie_blank"
            ]
        },
        "analyses": [
          {
            "type": "quality",
            "meta_data": {
              "example1": "some_example1"
            },
            "params": {
                "threshold_spoofing": 0.6,
                "extract_best_shot": true
            }
          }
]
    }
--BOUNDARY--

Пример успешного ответа

{
    "company_id": null,
    "time_created": 1720177371.120899,
    "folder_id": "folder_id", // временный ID
    "user_id": null,
    "resolution_endpoint": "https://www.your-custom-endpoint.com",
    "resolution_status": "FINISHED",
    "resolution_comment": "[]",
    "system_resolution": "SUCCESS",
    "resolution_time": null,
    "resolution_author_id": null,
    "resolution_state_hash": null,
    "operator_comment": null,
    "operator_status": null,
    "is_cleared": null,
    "meta_data": {
        "partner_side_folder_id": "partner_side_folder_id_if_needed",
        "person_info": {
            "first_name": "John",
            "middle_name": "Jameson",
            "last_name": "Doe"
        }
    },
    "technical_meta_data": {},
    "time_updated": 1720177375.531137,
    "media": [
        {
            "folder_id": "folder_id", // временный ID
            "media_id": "media_id", // временный ID
            "media_type": "VIDEO_FOLDER",
            "info": {
                "thumb": null,
                "video": {
                    "duration": 3.76,
                    "FPS": 22.83,
                    "width": 960,
                    "height": 720,
                    "md5": "8879b4fa9ee7add77aceb8d7d5d7b92d",
                    "size": 6017119,
                    "mime-type": "video/mp4"
                }
            },
            "tags": [
                "video_selfie",
                "video_selfie_blank",
                "orientation_portrait"
            ],
            "original_name": "video-5mb.mp4",
            "original_url": null,
            "company_id": null,
            "technical_meta_data": {},
            "time_created": 1719573752.781861,
            "time_updated": 1720177373.772401,
            "meta_data": {
                "foo4": "bar5"
            },
            "thumb_url": null,
            "folder_time_created": null,
            "video_id": "media_id", // временный ID
            "video_url": null
        }
    ],
    "analyses": [
        {
            "analyse_id": null,
            "analysis_id": null,
            "folder_id": "folder_id", // временный ID
            "folder_time_created": null,
            "type": "QUALITY",
            "state": "FINISHED",
            "company_id": null,
            "group_id": null,
            "results_data": null,
            "confs": {
                "threshold_replay": 0.5,
                "extract_best_shot": true,
                "threshold_liveness": 0.5,
                "threshold_spoofing": 0.42
            },
            "error_message": null,
            "error_code": null,
            "resolution_operator": null,
            "technical_meta_data": {},
            "time_created": 1720177371.121241,
            "time_updated": 1720177375.531043,
            "meta_data": {
                "some_key": "some_value"
            },
            "source_media": [
                {
                    "folder_id": "folder_id", // временный ID
                    "media_id": "media_id", // временный ID
                    "media_type": "VIDEO_FOLDER",
                    "info": {
                        "thumb": null,
                        "video": {
                            "duration": 3.76,
                            "FPS": 22.83,
                            "width": 960,
                            "height": 720,
                            "md5": "8879b4fa9ee7add77aceb8d7d5d7b92d",
                            "size": 6017119,
                            "mime-type": "video/mp4"
                        }
                    },
                    "tags": [
                        "video_selfie",
                        "video_selfie_blank",
                        "orientation_portrait"
                    ],
                    "original_name": "video-5mb.mp4",
                    "original_url": null,
                    "company_id": null,
                    "technical_meta_data": {},
                    "time_created": 1719573752.781861,
                    "time_updated": 1720177373.772401,
                    "meta_data": {
                        "foo4": "bar5"
                    },
                    "thumb_url": null,
                    "folder_time_created": null,
                    "video_id": "media_id", // временный ID
                    "video_url": null
                }
            ],
            "results_media": [
                {
                    "company_id": null,
                    "media_association_id": "media_id", // временный ID
                    "analysis_id": null,
                    "results_data": {
                        "confidence_spoofing": 0.000541269779
                    },
                    "source_media_id": "media_id", // temporary ID
                    "output_images": [
                        {
                            "folder_id": "folder_id", // временный ID
                            "media_id": "media_id", // временный ID
                            "media_type": "IMAGE_RESULT_ANALYSIS_SINGLE",
                            "info": {
                                "thumb": null,
                                "original": {
                                    "md5": "e6effeceb94e79b8cb204c6652283b57",
                                    "width": 720,
                                    "height": 960,
                                    "size": 145178,
                                    "mime-type": "image/jpeg"
                                }
                            },
                            "tags": [],
                            "original_name": "<PIL.JpegImagePlugin.JpegImageFile image mode=RGB size=720x960 at 0x766811DF8E90>",
                            "original_url": null,
                            "company_id": null,
                            "technical_meta_data": {},
                            "time_created": 1719573752.781861,
                            "time_updated": 1719573752.781871,
                            "meta_data": null,
                            "folder_time_created": null,
                            "image_b64": "",
                            "media_association_id": "media_id" // временный ID
                        }
                    ],
                    "collection_persons": [],
                    "folder_time_created": null
                }
            ],
            "resolution_status": "SUCCESS",
            "resolution": "SUCCESS"
        }
    ]
}

Поле payload

{
    "folder:meta_data": {
        "partner_side_folder_id": "partner_side_folder_id_if_needed",
        "person_info": {
            "first_name": "John",
            "middle_name": "Jameson",
            "last_name": "Doe"
        }   },
    "resolution_endpoint": "https://www.your-custom-endpoint.com",
    "media:meta_data": {
        "media_key1": {
            "foo": "bar2",
            "additional_info": "additional_info" // может влиять на оценку
        },
        "media_key2": {
            "foo2": "bar3"
        },
        "media_key3": {
            "foo4": "bar5"
        }
    },
    "media:tags": {
        "media_key1": [
            "video_selfie",
            "video_selfie_blank",
            "orientation_portrait"
        ],
        "media_key2": [
            "photo_selfie"
        ],
        "media_key3": [
            "video_selfie",
            "video_selfie_blank",
            "orientation_portrait"
        ]
    },
"analyses": [
    {
      "type": "quality",
      "meta_data": {
        "some_key": "some_value"
      },
      "params": {
      	"threshold_spoofing": 0.42, // влияет на результат
      	"extract_best_shot":true // вернется лучший кадр
      }
    }
  ]
}

Ошибки методов

Тип контента HTTP-ответа: “application/json”.

Коды ответов HTTP

Значение параметра “code”

Описание

400

LDE-002001

Неверный Content-type HTTP-запроса

400

LDE-002002

Неверный метод HTTP-запроса

400

LDE-002004

Не удалось прочитать биометрический образец*

400

LDE-002005

Неверный Content-Type части multiparted HTTP-запроса

500

LDE-001001

Внутренняя ошибка БП обнаружения витальности

400

LDE-001002

Ошибка TFSS. Необходимо вызвать метод liveness health.

Биометрический образец – входное изображение.

Методы API Lite

version – проверка версии компонентов

С помощью этого метода можно узнать, какие версии компонентов используются (начиная с версии 1.1.1).

Call GET /version

Входные параметры

Пример запроса

GET localhost/version

Успешный ответ метода

В случае успешного ответа метод возвращает сообщение со следующими параметрами.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

core

String

Версия API Lite.

tfss

String

Версия TFSS.

models

[String]

Массив версий моделей, где каждая запись содержит информацию о названии модели и ее версии.

Пример ответа

200 OK
Content-Type: application/json
{
2	"core": "core_version",
3	"tfss": "tfss_version",
4	"models": [
5		{
6			"name": "model_name",
7			"version": "model_version"
8		}
9	]
10}

Биометрия

health – проверка состояния биометрического процессора biometry

С помощью этого метода можно проверить, корректно ли работает процессор.

Вызов метода: GET /v1/face/pattern/health

Входные параметры

Пример запроса

GET localhost/v1/face/pattern/health

Успешный ответ метода

В случае успешного ответа метод возвращает сообщение со следующими параметрами.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

status

Int

0 – биометрический процессор работает корректно.

3 – биометрический процессор неработоспособен.

message

String

Сообщение.

Пример ответа

200 OK
Content-Type: application/json
{“status”: 0, message: “”}

extract – извлечение биометрического шаблона

Вызов метода: POST /v1/face/pattern/extract

Входные параметры

Наименование параметра

Тип

Описание

Не указывается*

Stream

Для параметров типа Stream имя указывать не нужно.

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/extract
Content-Type: image/jpeg
{Поток байт изображения}

Успешный ответ метода

В случае успешного ответа метод возвращает биометрический шаблон.

Тип контента HTTP-ответа: “application/octet-stream”.

Если в headers запроса передавалось поле Content-Transfer-Encoding со значением base64, то шаблон тоже вернется в base64.

Выходные параметры

Наименование параметра

Тип

Описание

Не указывается*

Stream

Биометрический шаблон, полученный из изображения

Для параметров типа Stream имя указывать не нужно.

Пример ответа

200 OK
Content-Type: application/octet-stream
{Поток байт биометрического шаблона}

compare – сравнение биометрических шаблонов

Метод предназначен для сравнения двух биометрических шаблонов.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/compare

Входные параметры

Наименование параметра

Тип

Описание

bio_feature

Stream

Обязательный параметр. Первый биометрический шаблон.

bio_template

Stream

Обязательный параметр. Второй биометрический шаблон.

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/compare
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”bio_feature”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”bio_template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результат сравнения двух шаблонов.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

score

Float

Результат сравнения двух шаблонов

decision

String

Рекомендуемое решение по полученному score.

approved – положительный результат. Лица совпадают.

operator_required – требуется дополнительная проверка оператора.

declined – негативный результат. Лица не совпадают.

Пример ответа

200 OK
Content-Type: application/json
{“score”: 1.0, “decision”: “approved”}

verify – биометрическая верификация

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/verify

Входные параметры

Наименование параметра

Тип

Описание

sample

Stream

Обязательный параметр. Изображение для извлечения биометрического шаблона.

bio_template

Stream

Обязательный параметр. Биометрический шаблон, с которым производится сравнение.

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/verify
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”bio_template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”sample”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результат сравнения двух биометрических шаблонов.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

score

Float

Результат сравнения двух шаблонов

decision

String

Рекомендуемое решение по полученному score.

approved – положительный результат. Лица совпадают.

operator_required – требуется дополнительная проверка оператора.

declined – негативный результат. Лица не совпадают.

Пример ответа

200 OK
Content-Type: application/json
{“score”: 1.0, “decision”: “approved”}

extract_and_compare – извлечение из двух изображений и сравнение полученных шаблонов

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/extract_and_compare

Входные параметры

Наименование параметра

Тип

Описание

sample_1

Stream

Обязательный параметр. Первое изображение.

sample_2

Stream

Обязательный параметр. Второе изображение

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/extract_and_compare
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”sample_1”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”sample_2”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результат сравнения двух извлеченных биометрических шаблонов.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

score

Float

Результат сравнения двух извлеченных шаблонов

decision

String

Рекомендуемое решение по полученному score.

approved – положительный результат. Лица совпадают.

operator_required – требуется дополнительная проверка оператора.

declined – негативный результат. Лица не совпадают.

Пример ответа

200 OK
Content-Type: application/json
{“score”: 1.0, “decision”: “approved”}

compare_n – сравнение биометрических шаблонов 1:N

Метод предназначен для сравнения биометрических шаблонов в режиме 1:N.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/compare_n

Входные параметры

Наименование параметра

Тип

Описание

template_1

Stream

Обязательный параметр.

Биометрический шаблон – кандидат(1).

templates_n

Stream

Обязательный параметр.

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/compare_n
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”template_1”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”1.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”2.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”3.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результаты сравнений 1:N .

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

results

List[JSON]

*filename

String

Значение filename в заголовке соответствующего шаблона из списка(N).

*score

Float

Результат сравнения кандидата с соответствующим шаблоном из списка(N).

*decision

String

Рекомендуемое решение по полученному score.

approved - положительный результат. Лица совпадают.

operator_required - требуется дополнительная проверка оператора.

declined - негативный результат. Лица не совпадают.

Пример ответа

200 OK
Content-Type: application/json
{'results': [
    {'filename': '1.template', 'score': 0.0, 'decision': 'declined'}, 
    {'filename': '2.template', 'score': 1.0, 'decision': 'approved'}, 
    {'filename': '3.template', 'score': 0.21, 'decision': 'declined'}
]}

verify_n – биометрическая верификация 1:N

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/verify_n

Входные параметры

Наименование параметра

Тип

Описание

sample_1

Stream

Обязательный параметр.

Изображение - кандидат(1).

templates_n

Stream

Обязательный параметр.

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/verify_n
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”sample_1”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”1.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”2.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”3.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результаты сравнений 1:N .

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

results

List[JSON]

*filename

String

Значение filename в заголовке соответствующего шаблона из списка(N).

*score

Float

Результат сравнения кандидата с соответствующим шаблоном из списка(N).

*decision

String

Рекомендуемое решение по полученному score.

approved - положительный результат. Лица совпадают.

operator_required - требуется дополнительная проверка оператора.

declined - негативный результат. Лица не совпадают.

Пример ответа

200 OK
Content-Type: application/json
{'results': [
    {'filename': '1.template', 'score': 0.0, 'decision': 'declined'}, 
    {'filename': '2.template', 'score': 1.0, 'decision': 'approved'}, 
    {'filename': '3.template', 'score': 0.21, 'decision': 'declined'}
]}

extract_and_compare_n – извлечение и сравнение полученных шаблонов 1:N

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/extract_and_compare_n

Входные параметры

Наименование параметра

Тип

Описание

sample_1

Stream

Обязательный параметр.

Изображение – кандидат(1).

samples_n

Stream

Обязательный параметр.

Для передачи данных в base64 необходимо в headers запроса передать Content-Transfer-Encoding = base64.

Пример запроса

POST localhost/v1/face/pattern/extract_and_compare_n
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”sample_1”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”samples_n”; filename=”1.jpeg”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”samples_n”; filename=”2.jpeg”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”samples_n”; filename=”3.jpeg”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результаты сравнений 1:N .

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

results

List[JSON]

*filename

String

Значение filename в заголовке соответствующего изображения из списка(N).

*score

Float

Результат сравнения кандидата с соответствующим изображением из списка(N).

*decision

String

Рекомендуемое решение по полученному score.

approved – положительный результат. Лица совпадают.

operator_required – требуется дополнительная проверка оператора.

declined – негативный результат. Лица не совпадают.

Пример ответа

200 OK
Content-Type: application/json
{'results': [
    {'filename': '1.jpeg', 'score': 0.0, 'decision': 'declined'}, 
    {'filename': '2.jpeg', 'score': 1.0, 'decision': 'approved'}, 
    {'filename': '3.jpeg', 'score': 0.21, 'decision': 'declined'}
]}

Ошибки методов

Тип контента HTTP-ответа: “application/json”.

Коды ответов HTTP

Значение параметра “code”

Описание

400

BPE-002001

Неверный Content-Type HTTP-запроса

400

BPE-002002

Неверный метод HTTP-запроса

400

BPE-002003

Не удалось прочитать *биометрический образец

400

BPE-002004

Не удалось прочитать биометрический шаблон

400

BPE-002005

Неверный Content-Type части multiparted HTTPзапроса

400

BPE-003001

Не удалось извлечь биометрический шаблон

400

BPE-003002

На биометрическом образце* отсутствует лицо

400

BPE-003003

На биометрическом образце* присутствует более одного лица

500

BPE-001001

Внутренняя ошибка биопроцессора

400

BPE-001002

Ошибка TFSS. Необходимо вызвать метод biometry health.

Биометрический образец – входное изображение.

Liveness

health – проверка состояния биометрического процессора liveness

Вызов метода: GET /v1/face/liveness/health

Входные параметры отсутствуют.

Пример запроса

GET localhost/v1/face/liveness/health

Успешный ответ метода

В случае успешного ответа метод возвращает сообщение со следующими параметрами.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Наименование параметра

Тип

Описание

status

Int

0 - биометрический процессор работает корректно.

3 - биометрический процессор неработоспособен.

message

String

Сообщение.

Пример ответа

200 OK
Content-Type: application/json
{“status”: 0, message: “”}

detect – обнаружение презентационных атак

Поддерживаются следующие Content-Type:

image/jpeg или image/png для изображения;
multipart/form-data для изображений, видео или архивов. Для добавления дополнительных параметров, влияющих на анализ, используйте payload.

Запуск метода:POST /{version}/face/liveness/detect.

Изображение

Принимает изображение в формате JPEG или PNG; без payload.

Пример запроса

POST /v1/face/liveness/detect HTTP/1.1
Host: localhost
Content-Type: image/jpeg
Content-Length: [длина тела сообщения]
[поток байт изображения]

Пример успешного ответа

HTTP/1.1 200 OK
Content-Type: application/json
{
  "passed": false,
  "score": 0.999484062
}

Multipart/form-data

Принимает запрос multipart/form-data.

Название каждого медиафайла должно быть уникальным, например, media_key1, media_key2.
Параметры payload должны быть в виде JSON, помещенного в поле payload.

Временные идентификаторы будут удалены после выполнения запроса.

Пример запроса

POST /v1/face/liveness/detect HTTP/1.1
Host: localhost
Content-Length: [длина тела сообщения]
Content-Type: multipart/form-data; boundary=--BOUNDARY--

--BOUNDARY--
Content-Disposition: form-data; name="media_key1"; filename="video.mp4"
Content-Type: multipart/form-data; 

[поток байт медиафайла]
--BOUNDARY--
Content-Disposition: form-data; name="payload"

    {
        "folder:meta_data": {
            "partner_side_folder_id": "partner_side_folder_id_if_needed",
            "person_info": {
                "first_name": "John",
                "middle_name": "Jameson",
                "last_name": "Doe"
            }
        },
        "resolution_endpoint": "https://www.your-custom-endpoint.com",
        "media:meta_data": {
            "media_key1": {
                "foo": "bar2"
            }
        },
        "media:tags": {
            "media_key1": [
                "video_selfie",
                "video_selfie_blank"
            ]
        },
        "analyses": [
          {
            "type": "quality",
            "meta_data": {
              "example1": "some_example1"
            },
            "params": {
                "threshold_spoofing": 0.6,
                "extract_best_shot": false
            }
          }
]
    }
--BOUNDARY--

Пример успешного ответа

{
    "company_id": null,
    "time_created": 1720180784.769608,
    "folder_id": "folder_id", // временный ID
    "user_id": null,
    "resolution_endpoint": "https://www.your-custom-endpoint.com",
    "resolution_status": "FINISHED",
    "resolution_comment": "[]",
    "system_resolution": "SUCCESS",
    "resolution_time": null,
    "resolution_author_id": null,
    "resolution_state_hash": null,
    "operator_comment": null,
    "operator_status": null,
    "is_cleared": null,
    "meta_data": {
        "partner_side_folder_id": "partner_side_folder_id_if_needed",
        "person_info": {
            "first_name": "John",
            "middle_name": "Jameson",
            "last_name": "Doe"
        }
    },
    "technical_meta_data": {},
    "time_updated": 1720180787.531983,
    "media": [
        {
            "folder_id": "folder_id", // временный ID
            "media_id": "video_id", // временный ID
            "media_type": "VIDEO_FOLDER",
            "info": {
                "thumb": null,
                "video": {
                    "duration": 3.76,
                    "FPS": 22.83,
                    "width": 960,
                    "height": 720,
                    "md5": "8879b4fa9ee7add77aceb8d7d5d7b92d",
                    "size": 6017119,
                    "mime-type": "video/mp4"
                }
            },
            "tags": [
                "video_selfie",
                "video_selfie_blank",
                "orientation_portrait"
            ],
            "original_name": "video-5mb.mp4",
            "original_url": null,
            "company_id": null,
            "technical_meta_data": {},
            "time_created": 1719573752.78253,
            "time_updated": 1720180787.531801,
            "meta_data": {
                "foo4": "bar5"
            },
            "thumb_url": null,
            "folder_time_created": null,
            "video_id": "video_id", // временный ID
            "video_url": null
        }
    ],
    "analyses": [
        {
            "analyse_id": null,
            "analysis_id": null,
            "folder_id": "folder_id", // временный ID
            "folder_time_created": null,
            "type": "QUALITY",
            "state": "FINISHED",
            "company_id": null,
            "group_id": null,
            "results_data": null,
            "confs": {
                "threshold_replay": 0.5,
                "extract_best_shot": false,
                "threshold_liveness": 0.5,
                "threshold_spoofing": 0.42
            },
            "error_message": null,
            "error_code": null,
            "resolution_operator": null,
            "technical_meta_data": {},
            "time_created": 1720180784.769944,
            "time_updated": 1720180787.531877,
            "meta_data": {
                "some_key": "some_value"
            },
            "source_media": [
                {
                    "folder_id": "folder_id", // временный ID
                    "media_id": "video_id", // временный ID
                    "media_type": "VIDEO_FOLDER",
                    "info": {
                        "thumb": null,
                        "video": {
                            "duration": 3.76,
                            "FPS": 22.83,
                            "width": 960,
                            "height": 720,
                            "md5": "8879b4fa9ee7add77aceb8d7d5d7b92d",
                            "size": 6017119,
                            "mime-type": "video/mp4"
                        }
                    },
                    "tags": [
                        "video_selfie",
                        "video_selfie_blank",
                        "orientation_portrait"
                    ],
                    "original_name": "video-5mb.mp4",
                    "original_url": null,
                    "company_id": null,
                    "technical_meta_data": {},
                    "time_created": 1719573752.78253,
                    "time_updated": 1720180787.531801,
                    "meta_data": {
                        "foo4": "bar5"
                    },
                    "thumb_url": null,
                    "folder_time_created": null,
                    "video_id": "video_id", // временный ID
                    "video_url": null
                }
            ],
            "results_media": [
                {
                    "company_id": null,
                    "media_association_id": "video_id", // временный ID
                    "analysis_id": null,
                    "results_data": {
                        "confidence_spoofing": 0.000541269779
                    },
                    "source_media_id": "video_id", // временный ID
                    "output_images": [],
                    "collection_persons": [],
                    "folder_time_created": null
                }
            ],
            "resolution_status": "SUCCESS",
            "resolution": "SUCCESS"
        }
    ]
}

Multipart/form-data с Best Shot

Пример запроса

POST /v1/face/liveness/detect HTTP/1.1
Host: localhost
Content-Length: [длина тела сообщения]
Content-Type: multipart/form-data; boundary=--BOUNDARY--

--BOUNDARY--
Content-Disposition: form-data; name="media_key1"; filename="video.mp4"
Content-Type: multipart/form-data; 

[поток байт медиафайла]
--BOUNDARY--
Content-Disposition: form-data; name="payload"

    {
        "folder:meta_data": {
            "partner_side_folder_id": "partner_side_folder_id_if_needed",
            "person_info": {
                "first_name": "John",
                "middle_name": "Jameson",
                "last_name": "Doe"
            }
        },
        "resolution_endpoint": "https://www.your-custom-endpoint.com",
        "media:meta_data": {
            "media_key1": {
                "foo": "bar2"
            }
        },
        "media:tags": {
            "media_key1": [
                "video_selfie",
                "video_selfie_blank"
            ]
        },
        "analyses": [
          {
            "type": "quality",
            "meta_data": {
              "example1": "some_example1"
            },
            "params": {
                "threshold_spoofing": 0.6,
                "extract_best_shot": true
            }
          }
]
    }
--BOUNDARY--

Пример успешного ответа

{
    "company_id": null,
    "time_created": 1720177371.120899,
    "folder_id": "folder_id", // временный ID
    "user_id": null,
    "resolution_endpoint": "https://www.your-custom-endpoint.com",
    "resolution_status": "FINISHED",
    "resolution_comment": "[]",
    "system_resolution": "SUCCESS",
    "resolution_time": null,
    "resolution_author_id": null,
    "resolution_state_hash": null,
    "operator_comment": null,
    "operator_status": null,
    "is_cleared": null,
    "meta_data": {
        "partner_side_folder_id": "partner_side_folder_id_if_needed",
        "person_info": {
            "first_name": "John",
            "middle_name": "Jameson",
            "last_name": "Doe"
        }
    },
    "technical_meta_data": {},
    "time_updated": 1720177375.531137,
    "media": [
        {
            "folder_id": "folder_id", // временный ID
            "media_id": "media_id", // временный ID
            "media_type": "VIDEO_FOLDER",
            "info": {
                "thumb": null,
                "video": {
                    "duration": 3.76,
                    "FPS": 22.83,
                    "width": 960,
                    "height": 720,
                    "md5": "8879b4fa9ee7add77aceb8d7d5d7b92d",
                    "size": 6017119,
                    "mime-type": "video/mp4"
                }
            },
            "tags": [
                "video_selfie",
                "video_selfie_blank",
                "orientation_portrait"
            ],
            "original_name": "video-5mb.mp4",
            "original_url": null,
            "company_id": null,
            "technical_meta_data": {},
            "time_created": 1719573752.781861,
            "time_updated": 1720177373.772401,
            "meta_data": {
                "foo4": "bar5"
            },
            "thumb_url": null,
            "folder_time_created": null,
            "video_id": "media_id", // временный ID
            "video_url": null
        }
    ],
    "analyses": [
        {
            "analyse_id": null,
            "analysis_id": null,
            "folder_id": "folder_id", // временный ID
            "folder_time_created": null,
            "type": "QUALITY",
            "state": "FINISHED",
            "company_id": null,
            "group_id": null,
            "results_data": null,
            "confs": {
                "threshold_replay": 0.5,
                "extract_best_shot": true,
                "threshold_liveness": 0.5,
                "threshold_spoofing": 0.42
            },
            "error_message": null,
            "error_code": null,
            "resolution_operator": null,
            "technical_meta_data": {},
            "time_created": 1720177371.121241,
            "time_updated": 1720177375.531043,
            "meta_data": {
                "some_key": "some_value"
            },
            "source_media": [
                {
                    "folder_id": "folder_id", // временный ID
                    "media_id": "media_id", // временный ID
                    "media_type": "VIDEO_FOLDER",
                    "info": {
                        "thumb": null,
                        "video": {
                            "duration": 3.76,
                            "FPS": 22.83,
                            "width": 960,
                            "height": 720,
                            "md5": "8879b4fa9ee7add77aceb8d7d5d7b92d",
                            "size": 6017119,
                            "mime-type": "video/mp4"
                        }
                    },
                    "tags": [
                        "video_selfie",
                        "video_selfie_blank",
                        "orientation_portrait"
                    ],
                    "original_name": "video-5mb.mp4",
                    "original_url": null,
                    "company_id": null,
                    "technical_meta_data": {},
                    "time_created": 1719573752.781861,
                    "time_updated": 1720177373.772401,
                    "meta_data": {
                        "foo4": "bar5"
                    },
                    "thumb_url": null,
                    "folder_time_created": null,
                    "video_id": "media_id", // временный ID
                    "video_url": null
                }
            ],
            "results_media": [
                {
                    "company_id": null,
                    "media_association_id": "media_id", // временный ID
                    "analysis_id": null,
                    "results_data": {
                        "confidence_spoofing": 0.000541269779
                    },
                    "source_media_id": "media_id", // temporary ID
                    "output_images": [
                        {
                            "folder_id": "folder_id", // временный ID
                            "media_id": "media_id", // временный ID
                            "media_type": "IMAGE_RESULT_ANALYSIS_SINGLE",
                            "info": {
                                "thumb": null,
                                "original": {
                                    "md5": "e6effeceb94e79b8cb204c6652283b57",
                                    "width": 720,
                                    "height": 960,
                                    "size": 145178,
                                    "mime-type": "image/jpeg"
                                }
                            },
                            "tags": [],
                            "original_name": "<PIL.JpegImagePlugin.JpegImageFile image mode=RGB size=720x960 at 0x766811DF8E90>",
                            "original_url": null,
                            "company_id": null,
                            "technical_meta_data": {},
                            "time_created": 1719573752.781861,
                            "time_updated": 1719573752.781871,
                            "meta_data": null,
                            "folder_time_created": null,
                            "image_b64": "",
                            "media_association_id": "media_id" // временный ID
                        }
                    ],
                    "collection_persons": [],
                    "folder_time_created": null
                }
            ],
            "resolution_status": "SUCCESS",
            "resolution": "SUCCESS"
        }
    ]
}

Поле payload

{
    "folder:meta_data": {
        "partner_side_folder_id": "partner_side_folder_id_if_needed",
        "person_info": {
            "first_name": "John",
            "middle_name": "Jameson",
            "last_name": "Doe"
        }   },
    "resolution_endpoint": "https://www.your-custom-endpoint.com",
    "media:meta_data": {
        "media_key1": {
            "foo": "bar2",
            "additional_info": "additional_info" // может влиять на оценку
        },
        "media_key2": {
            "foo2": "bar3"
        },
        "media_key3": {
            "foo4": "bar5"
        }
    },
    "media:tags": {
        "media_key1": [
            "video_selfie",
            "video_selfie_blank",
            "orientation_portrait"
        ],
        "media_key2": [
            "photo_selfie"
        ],
        "media_key3": [
            "video_selfie",
            "video_selfie_blank",
            "orientation_portrait"
        ]
    },
"analyses": [
    {
      "type": "quality",
      "meta_data": {
        "some_key": "some_value"
      },
      "params": {
      	"threshold_spoofing": 0.42, // влияет на результат
      	"extract_best_shot":true // вернется лучший кадр
      }
    }
  ]
}

Ошибки методов

Тип контента HTTP-ответа: “application/json”.

Коды ответов HTTP

Значение параметра “code”

Описание

400

LDE-002001

Неверный Content-type HTTP-запроса

400

LDE-002002

Неверный метод HTTP-запроса

400

LDE-002004

Не удалось прочитать биометрический образец*

400

LDE-002005

Неверный Content-Type части multiparted HTTP-запроса

500

LDE-001001

Внутренняя ошибка БП обнаружения витальности

400

LDE-001002

Ошибка TFSS. Необходимо вызвать метод liveness health.

Биометрический образец – входное изображение.