# Методы API Lite
{% hint style="info" %}
Начиная с версии 1.1.0, Oz API Lite может принимать изображения и шаблоны в формате base64, а также возвращать в этом формате шаблоны биометрических проверок. Для включения этой опции необходимо в headers запроса передать `Content-Transfer-Encoding = base64`.
{% endhint %}
### **version – проверка версии компонентов**
С помощью этого метода можно узнать, какие версии компонентов используются (начиная с версии 1.1.1).
Call `GET /version`
**Входные параметры**
\-
#### **Пример запроса**
`GET localhost/version`
#### **Успешный ответ метода**
В случае успешного ответа метод возвращает сообщение со следующими параметрами.
Тип контента HTTP-ответа: “application/json”.
#### **Выходные параметры**
| **Наименование параметра** | **Тип** | **Описание** |
| -------------------------- | --------- | ------------------------------------------------------------------------------------------- |
| core | String | Версия API Lite. |
| tfss | String | Версия TFSS. |
| models | \[String] | Массив версий моделей, где каждая запись содержит информацию о названии модели и ее версии. |
#### **Пример ответа**
```json
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 | Сообщение. |
#### **Пример ответа**
```json
200 OK
Content-Type: application/json
{“status”: 0, message: “”}
```
### **extract – извлечение биометрического шаблона**
Метод предназначен для извлечения биометрического шаблона из изображения.\
Тип контента HTTP-запроса: “image/jpeg” или “image/png”
Вызов метода: `POST /v1/face/pattern/extract`
#### **Входные параметры**
| **Наименование параметра** | **Тип** | **Описание** |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Не указывается\* | Stream | Обязательный параметр. Изображение для извлечения биометрического шаблона.
В заголовочном поле “Content-Type” должен быть указан тип контента.
|
*
Для параметров типа Stream имя указывать не нужно.
{% hint style="info" %}
Для передачи данных в base64 необходимо в headers запроса передать `Content-Transfer-Encoding = base64`.
{% endhint %}
#### **Пример запроса**
```json
POST localhost/v1/face/pattern/extract
Content-Type: image/jpeg
{Поток байт изображения}
```
#### **Успешный ответ метода**
В случае успешного ответа метод возвращает биометрический шаблон.
Тип контента HTTP-ответа: “application/octet-stream”.
{% hint style="info" %}
Если в headers запроса передавалось поле Content-Transfer-Encoding со значением base64, то шаблон тоже вернется в base64.
{% endhint %}
#### **Выходные параметры**
| **Наименование параметра** | **Тип** | **Описание** |
| -------------------------- | ------- | ------------------------------------------------ |
| Не указывается\* | Stream | Биометрический шаблон, полученный из изображения |
*
Для параметров типа Stream имя указывать не нужно.
#### **Пример ответа**
```json
200 OK
Content-Type: application/octet-stream
{Поток байт биометрического шаблона}
```
### **compare – сравнение биометрических шаблонов**
Метод предназначен для сравнения двух биометрических шаблонов.
Тип контента HTTP-запроса: “multipart/form-data”.
Вызов метода: `POST /v1/face/pattern/compare`
#### **Входные параметры**
| **Наименование параметра** | **Тип** | **Описание** |
| -------------------------- | ------- | -------------------------------------------------------------- |
| bio\_feature | Stream | Обязательный параметр.
Первый биометрический шаблон.
|
| bio\_template | Stream | Обязательный параметр.
Второй биометрический шаблон.
|
{% hint style="info" %}
Для передачи данных в base64 необходимо в headers запроса передать `Content-Transfer-Encoding = base64`.
{% endhint %}
#### **Пример запроса**
```json
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 – негативный результат. Лица не совпадают.
|
#### **Пример ответа**
```json
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 | Обязательный параметр.
Биометрический шаблон, с которым производится сравнение.
|
{% hint style="info" %}
Для передачи данных в base64 необходимо в headers запроса передать `Content-Transfer-Encoding = base64`.
{% endhint %}
#### **Пример запроса**
```json
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 – негативный результат. Лица не совпадают.
|
#### **Пример ответа**
```json
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 | Обязательный параметр.
Второе изображение
|
{% hint style="info" %}
Для передачи данных в base64 необходимо в headers запроса передать `Content-Transfer-Encoding = base64`.
{% endhint %}
#### **Пример запроса**
```json
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 – негативный результат. Лица не совпадают.
|
#### **Пример ответа**
```json
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.
|
{% hint style="info" %}
Для передачи данных в base64 необходимо в headers запроса передать `Content-Transfer-Encoding = base64`.
{% endhint %}
#### **Пример запроса**
```json
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 - негативный результат. Лица не совпадают.
|
#### **Пример ответа**
```json
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 | Обязательный параметр.
Список(N) биометрических шаблонов. Каждый биометрический шаблон должен быть передан отдельно, но необходимо чтобы имя параметра было templates\_n. Также требуется, чтобы в заголовке был передан filename.
|
{% hint style="info" %}
Для передачи данных в base64 необходимо в headers запроса передать `Content-Transfer-Encoding = base64`.
{% endhint %}
#### **Пример запроса**
```json
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] | Список результатов сравнения кандидата со списком(N). Для каждого сравнения из списка(N) результат имеет следующие поля: |
| \*filename | String | Значение filename в заголовке соответствующего шаблона из списка(N). |
| \*score | Float | Результат сравнения кандидата с соответствующим шаблоном из списка(N). |
| \*decision | String | Рекомендуемое решение по полученному score.
approved - положительный результат. Лица совпадают.
operator\_required - требуется дополнительная проверка оператора.
declined - негативный результат. Лица не совпадают.
|
#### **Пример ответа**
```json
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.
|
{% hint style="info" %}
Для передачи данных в base64 необходимо в headers запроса передать `Content-Transfer-Encoding = base64`.
{% endhint %}
#### **Пример запроса**
```json
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] | Список результатов сравнения кандидата со списком(N). Для каждого сравнения из списка(N) результат имеет следующие поля: |
| \*filename | String | Значение filename в заголовке соответствующего изображения из списка(N). |
| \*score | Float | Результат сравнения кандидата с соответствующим изображением из списка(N). |
| \*decision | String | Рекомендуемое решение по полученному score.
approved – положительный результат. Лица совпадают.
operator\_required – требуется дополнительная проверка оператора.
declined – негативный результат. Лица не совпадают.
|
#### **Пример ответа**
```json
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 | Сообщение. |
#### **Пример ответа**
```json
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`.
Пример запроса
```json
POST /v1/face/liveness/detect HTTP/1.1
Host: localhost
Content-Type: image/jpeg
Content-Length: [длина тела сообщения]
[поток байт изображения]
```
Пример успешного ответа
```json
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`.
{% hint style="info" %}
Временные идентификаторы будут удалены после выполнения запроса.
{% endhint %}
Пример запроса
```json
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--
```
Пример успешного ответа
```json
{
"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 будет считаться пройденной.
Пример запроса
```json
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--
```
Пример успешного ответа
```json
{
"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": "",
"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
```json
{
"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. |
*
Биометрический образец – входное изображение.