Перейти к основному содержимому

# API запросы для работы с попыткой

## Запрос на получение списка попыток​

Данный запрос возвращает список попыток (endeavor) в разрезе внешних ссылок в формате страниц. Поддерживается фильтрация по временному диапазону создания попыток. Результаты сортируются по времени создания; направление сортировки можно изменять.

Схема запроса:
`GET /lrs/endeavor?sort_order={sort_order}&page={page_number}&page_size={page_size}`

### Параметры запроса​

Параметр | Описание
--- | ---
`sort_order` | Порядок сортировки по времени создания. Возможные значения: `asc` (по возрастанию), `desc` (по убыванию). Обязательный.
`page` | Номер запрашиваемой страницы. Минимальное значение: `1`. Обязательный.
`page_size` | Количество элементов на странице. Допустимый диапазон: от 1 до 100. Обязательный.
`external_link` | Фильтр по внешней ссылке. Если не указан, возвращаются все попытки, у которых `external_link` равен `null`.
`start_date` | Нижняя граница временного диапазона создания попыток (включительно).
`end_date` | Верхняя граница временного диапазона создания попыток (не включительно).

### Заголовки запроса​

Заголовок | Описание
--- | ---
`token` | Токен сервиса `video-recorder`. Хранится в секрете `video-recorder-token` в файле `./cfg/video-recorder.secrets.json`.

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

    curl -X 'GET' \
      'http://192.168.10.1/lrs/endeavor?sort_order=asc&page=1&page_size=1' \
      -H 'accept: application/json' \
      -H 'token: token'

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

    {
      "page": 1,
      "page_size": 1,
      "total_count": 8,
      "endeavor_list": [
        {
          "id": "e4823024-d578-4285-9d3b-0471a4f720b2",
          "external_link": null,
          "content": [
            {
              "id": "5e77c40a-f45e-4a7e-ade8-8f676bc691f1",
              "files": [
                {
                  "s3_link": "lr.videos:motion_control_video-26-07-06-12_38_10-no-parent-e4823-5e77c.webm",
                  "raw_data_in_base64": null
                }
              ],
              "type": 1,
              "parent_id": null,
              "info": {
                "motion_control_result": [
                  { "result": true, "pattern": "right" },
                  { "result": true, "pattern": "left" },
                  { "result": true, "pattern": "left" }
                ]
              },
              "exception_info": null,
              "creation_date": "2026-07-06T12:38:10.960546Z",
              "last_modified": "2026-07-06T12:38:10.960546Z"
            },
            {
              "id": "ac16bccc-478e-48ec-80e6-7cd0666a5e83",
              "files": [
                {
                  "s3_link": "lr.ref-images:reference_frame-26-07-06-12_38_10-5e77c-e4823-ac16b.jpeg",
                  "raw_data_in_base64": null
                }
              ],
              "type": 3,
              "parent_id": "5e77c40a-f45e-4a7e-ade8-8f676bc691f1",
              "info": {
                "angles": [0, -2],
                "image_info": {
                  "quality": {
                    "value": true,
                    "failed_checks": null
                  },
                  "deepfake": {
                    "confidence": 0.00021070241928100586
                  },
                  "liveness": {
                    "value": "real",
                    "confidence": 0.9773591756820679,
                    "attack_type": "none",
                    "attack_type_scores": {
                      "none": 0.9773591756820679,
                      "photo": 0.0008513810934558892,
                      "replay": 0.007360487079161384,
                      "2d_mask": 0.0008028665221645174,
                      "3d_mask": 0.0017056756156491595,
                      "regions": 0.011920414007501181
                    }
                  }
                },
                "frame_number": 128
              },
              "exception_info": null,
              "creation_date": "2026-07-06T12:38:10.960546Z",
              "last_modified": "2026-07-06T12:38:10.960546Z"
            },
            {
              "id": "ce79a10b-26c1-4ccb-9c21-6f5439569a77",
              "files": [],
              "type": 5,
              "parent_id": null,
              "info": {
                "verification_info": {
                  "fa_r": 0,
                  "fr_r": 0.6750852465629578,
                  "score": 0.9856855273246765,
                  "distance": 2339
                }
              },
              "exception_info": null,
              "creation_date": "2026-07-06T12:38:12.671648Z",
              "last_modified": "2026-07-06T12:38:12.671648Z"
            }
          ],
          "creation_date": "2026-07-06T12:37:58.219058Z",
          "last_modified": "2026-07-06T12:37:58.219058Z"
        }
      ]
    }

Ответ содержит следующие поля:

Поле | Описание
--- | ---
`page` | Номер текущей страницы (соответствует переданному в запросе).
`page_size` | Количество элементов на странице (соответствует переданному в запросе).
`total_count` | Общее количество попыток, удовлетворяющих критериям фильтрации.
`endeavor_list` | Массив попыток на текущей странице. Подробнее о объекте попытки можно узнать в этом разделе

## Запрос на получение конкретной попытки по id​

Данный запрос возвращает попытку (endeavor) по её id. ID попытки можно получить через callback-и веб-компоненты.

Схема запроса:
`GET /lrs/endeavor/{endeavor_id}`

### Заголовки запроса​

Заголовок | Описание
--- | ---
`token` | Токен сервиса `video-recorder`. Хранится в секрете `video-recorder-token` в файле `./cfg/video-recorder.secrets.json`..

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

    curl -X 'GET' \
      'http://192.168.10.1/lrs/endeavor/e4823024-d578-4285-9d3b-0471a4f720b2' \
      -H 'accept: application/json' \
      -H 'token: token'

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

    {
      "id": "e4823024-d578-4285-9d3b-0471a4f720b2",
      "external_link": null,
      "content": [
        {
          "id": "5e77c40a-f45e-4a7e-ade8-8f676bc691f1",
          "files": [
            {
              "s3_link": "lr.videos:motion_control_video-26-07-06-12_38_10-no-parent-e4823-5e77c.webm",
              "raw_data_in_base64": null
            }
          ],
          "type": 1,
          "parent_id": null,
          "info": {
            "motion_control_result": [
              {
                "result": true,
                "pattern": "right"
              },
              {
                "result": true,
                "pattern": "left"
              },
              {
                "result": true,
                "pattern": "left"
              }
            ]
          },
          "exception_info": null,
          "creation_date": "2026-07-06T12:38:10.960546Z",
          "last_modified": "2026-07-06T12:38:10.960546Z"
        },
        {
          "id": "ac16bccc-478e-48ec-80e6-7cd0666a5e83",
          "files": [
            {
              "s3_link": "lr.ref-images:reference_frame-26-07-06-12_38_10-5e77c-e4823-ac16b.jpeg",
              "raw_data_in_base64": null
            }
          ],
          "type": 3,
          "parent_id": "5e77c40a-f45e-4a7e-ade8-8f676bc691f1",
          "info": {
            "angles": [
              0,
              -2
            ],
            "image_info": {
              "quality": {
                "value": true,
                "failed_checks": null
              },
              "deepfake": {
                "confidence": 0.00021070241928100586
              },
              "liveness": {
                "value": "real",
                "confidence": 0.9773591756820679,
                "attack_type": "none",
                "attack_type_scores": {
                  "none": 0.9773591756820679,
                  "photo": 0.0008513810934558892,
                  "replay": 0.007360487079161384,
                  "2d_mask": 0.0008028665221645174,
                  "3d_mask": 0.0017056756156491595,
                  "regions": 0.011920414007501181
                }
              }
            },
            "frame_number": 128
          },
          "exception_info": null,
          "creation_date": "2026-07-06T12:38:10.960546Z",
          "last_modified": "2026-07-06T12:38:10.960546Z"
        },
        {
          "id": "ce79a10b-26c1-4ccb-9c21-6f5439569a77",
          "files": [],
          "type": 5,
          "parent_id": null,
          "info": {
            "verification_info": {
              "fa_r": 0,
              "fr_r": 0.6750852465629578,
              "score": 0.9856855273246765,
              "distance": 2339
            }
          },
          "exception_info": null,
          "creation_date": "2026-07-06T12:38:12.671648Z",
          "last_modified": "2026-07-06T12:38:12.671648Z"
        }
      ],
      "creation_date": "2026-07-06T12:37:58.219058Z",
      "last_modified": "2026-07-06T12:37:58.219058Z"
    }

## Запрос на получение контента по S3 ссылке​

Данный запрос возвращает бинарный контент по S3 ссылке. S3 ссылку можно получить из попытки.

Схема запроса:
`GET /lrs/get_content/{content_link}`

### Заголовки запроса​

Заголовок | Описание
--- | ---
`token` | Токен сервиса `video-recorder`. Хранится в секрете `video-recorder-token` в файле `./cfg/video-recorder.secrets.json`..

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

    curl -X 'GET' \
      'http://192.168.10.1/lrs/get_content/lr.ref-images%3Areference_frame-26-07-06-12_38_10-5e77c-e4823-ac16b.jpeg' \
      -H 'accept: application/json' \
      -H 'token: token'

# API-запросы для ручного обработки фото

В данном разделе описаны запросы, позволяющие выполнить детекцию лица на изображении, построить биометрический шаблон и сравнить два таких шаблона между собой. Вот улучшенный текст с исправленными ошибками и дополненным описанием полей:

## Запрос на обнаружение лица на изображении​

Данный запрос выполняет детекцию лица на переданной фотографии и возвращает его координаты и ключевые точки.

Схема запроса:
`POST /face-detector-face-fitter/v2/process/image`

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

    curl -X 'POST' \
      'http://192.168.10.1/face-detector-face-fitter/v2/process/image' \
      -H 'accept: application/json' \
      -H 'Content-Type: multipart/form-data' \
      -F 'image=@MinimumIMG.jpeg;type=image/jpeg'

### Параметры тела запроса (multipart/form-data)​

Параметр | Описание
--- | ---
`image` | Изображение для обработки. Поддерживаемые форматы: `jpeg`, `png`. Обязательный.

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

    {
      "_image": {
        "blob": "/9j/4A...",
        "format": "IMAGE"
      },
      "objects": [
        {
          "keypoints": {
            ....
          },
          "pose": {
            "yaw": -8.746259689331055,
            "roll": -0.09920386970043182,
            "pitch": 2.89003586769104
          },
          "confidence": 0.8694550395011902,
          "id": 0,
          "bbox": [
            0.2,
            0.21,
            0.8466666666666667,
            0.8433333333333334
          ],
          "class": "face"
        }
      ]
    }

### Структура ответа​

Поле | Описание
--- | ---
`_image` | Исходное изображение, переданное на вход, в формате Base64.
`objects` | Список объектов, обнаруженных на изображении, с результатами их обработки. Если список пуст, детектор не обнаружил ни одного лица.
`objects[*].bbox` | Границы обнаруженного лица, заданные в относительных координатах (нормированных от 0 до 1) в порядке `[x1, y1, x2, y2]`. Для перевода в абсолютные пиксельные координаты необходимо умножить x-коэффициенты на ширину исходного изображения, а y-коэффициенты — на его высоту.

## Запрос на детекцию лица и построение шаблона​

Данный запрос обнаруживает лицо на переданной фотографии и строит для него поисковый биометрический шаблон.

Схема запроса:
`POST /face-detector-template-extractor/v2/process/image`

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

    curl -X 'POST' \
      'http://192.168.10.1/face-detector-template-extractor/v2/process/image' \
      -H 'accept: application/json' \
      -H 'Content-Type: multipart/form-data' \
      -F 'image=@MinimumIMG.jpeg;type=image/jpeg'

### Параметры тела запроса (multipart/form-data)​

Параметр | Описание
--- | ---
`image` | Изображение для обработки. Поддерживаемые форматы: `jpeg`, `png`. Обязательный.

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

    {
      "_image": {
        "blob": "/9j/4....",
        "format": "IMAGE"
      },
      "objects": [
        {
          "template": {
            "_face_template_extractor_1000_12": {
              "blob": "qjdp2UD...",
              "format": "NDARRAY",
              "dtype": "uint8",
              "shape": [296]
            }
          },
          "confidence": 0.8694550395011902,
          "id": 0,
          "bbox": [0.2, 0.21, 0.8466666666666667, 0.8433333333333334],
          "class": "face",
          "keypoints": { ... },
          "pose": { ... }
        }
      ]
    }

### Структура ответа​

Поле | Описание
--- | ---
`_image` | Исходное изображение, переданное на вход, в формате Base64.
`objects` | Список объектов, обнаруженных на изображении, с результатами их обработки. Если список пуст, детектор не обнаружил ни одного лица.
`objects[*].template` | Информация о биометрическом шаблоне, включая его бинарные данные в формате Base64.

## Запрос на оценку живости по изображению​

Данный запрос выполняет проверку живости (liveness) для ранее обнаруженного лица на фотографии.

Схема запроса:
`POST /liveness-estimator/v2/process/sample`

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

    curl -X 'POST' \
      'http://192.168.10.1/liveness-estimator/v2/process/sample' \
      -H 'accept: application/json' \
      -H 'Content-Type: application/json' \
      -d '{
      "objects": [
        ...
      ]
    }'

### Параметры тела запроса (application/json)​

На вход подаётся результат выполнения запроса на детекцию лица или построение шаблона. Тело запроса должно содержать:

Поле | Описание
--- | ---
`_image` | Исходное изображение в формате Base64, переданное на вход предыдущему обработчику.
`objects` | Список обнаруженных объектов (должен содержать как минимум одно лицо). Если список пуст, алгоритм не сможет выполнить оценку живости.

#### Пример тела запроса​

    {
      "_image": {
        "blob": "/9j/4AAQSkZJRg...",
        "format": "IMAGE"
      },
      "objects": [
        {
          "keypoints": {...},
          "pose": {...},
          "confidence": 0.8694550395011902,
          "id": 0,
          "bbox": [...],
          "class": "face"
        }
      ]
    }

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

    {
      "_image": {
        "blob": "/9j/4AAQSkZJ...",
        "format": "IMAGE"
      },
      "objects": [
        {
          "keypoints": {...},
          "pose": {...},
          "confidence": 0.8694550395011902,
          "id": 0,
          "bbox": [...],
          "class": "face",
          "liveness": {
            "confidence": 0.9966132640838623,
            "value": "real",
            "attack_type": "none",
            "attack_type_scores": {
              "none": 0.9966132640838623,
              "replay": 0.000978723779512078,
              "photo": 0.0021829818897145916,
              "regions": 9.736091756044222e-05,
              "2d_mask": 9.789085341223873e-05,
              "3d_mask": 2.977847593834453e-05
            }
          }
        }
      ]
    }

### Структура ответа​

В ответе возвращается тот же объект `_image` и дополненный список `objects`. Для каждого обнаруженного лица добавляется блок `liveness`:

Поле | Описание
--- | ---
`objects[*].liveness.value` | Вердикт алгоритма живости: `"real"` — живой человек.
`objects[*].liveness.confidence` | Уверенность алгоритма, что на фото живой человек. Чем выше, тем лучше.
`objects[*].liveness.attack_type` | Распознанный тип атаки (`"none"` — атаки нет).
`objects[*].liveness.attack_type_scores` | Уверенность алгоритма по каждому типу атаки.

## Запрос на сравнение шаблонов​

Данный запрос сравнивает два биометрических шаблона, полученных с помощью запроса на построение шаблона.

Схема запроса:
`POST /verify-matcher/v2/process/sample`

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

    curl -X 'POST' \
      'http://192.168.10.1/verify-matcher/v2/process/sample' \
      -H 'accept: application/json' \
      -H 'Content-Type: application/json' \
      -d '{
      "objects": [
        ...
      ]
    }'

### Параметры тела запроса (application/json)​

На вход подаётся список из двух шаблонов, подлежащих сравнению. Порядок элементов не важен.

Тело запроса содержит поле `objects` — массив объектов с шаблонами. Каждый объект должен содержать:

Поле | Описание
--- | ---
`template` | Биометрический шаблон. Значение должно быть скопировано целиком из поля `template` ответа API построения шаблонов.
`class` | Тип объекта. Всегда должен иметь значение `face`.

#### Пример тела запроса​

    {
      "objects": [
        {
          "template": {
            "_face_template_extractor_1000_12": {
              "blob": "qjdp...",
              "format": "NDARRAY",
              "dtype": "uint8",
              "shape": [296]
            }
          },
          "class": "face"
        },
        {
          "template": {
            "_face_template_extractor_1000_12": {
              "blob": "qjdp...",
              "format": "NDARRAY",
              "dtype": "uint8",
              "shape": [296]
            }
          },
          "class": "face"
        }
      ]
    }

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

    {
      "objects": [
        ...
      ],
      "verification": {
        "distance": 0,
        "fa_r": 0,
        "fr_r": 0.9825811982154846,
        "score": 0.9773591756820679
      }
    }

### Структура ответа​

Поле | Описание
--- | ---
`objects` | Список объектов, переданных на вход (возвращается без изменений).
`verification` | Результат сравнения двух шаблонов.
`verification.score` | Уверенность алгоритма в том, что лица принадлежат одному человеку. Чем выше значение, тем выше вероятность совпадения.

# Структура объекта попытки

## Поля объекта попытки (endeavor)​

Поле | Описание
--- | ---
`id` | Уникальный идентификатор попытки.
`external_link` | Внешняя ссылка, привязанная к попытке.
`content` | Список элементов контента (обработанные бинарные данные). Каждый элемент содержит ссылки на бинарные данные и результаты их обработки.
`creation_date` | Дата и время создания попытки.
`last_modified` | Дата и время последнего изменения.

## Поля элемента контента (content)​

Поле | Описание
--- | ---
`id` | Уникальный идентификатор элемента контента.
`files` | Список S3-ссылок на файлы. Содержит ссылки на видео или изображения в зависимости от типа контента. Верификационные кадры не сохраняются.
`type` | Тип контента: `1` — видео контроля движений, `3` — референсный кадр, `5` — верификационный кадр.
`info` | Результаты биометрической обработки. Формат зависит от типа контента.
`exception_info` | Информация об ошибках, возникших при обработке контента.

### Тип контента 1 — видео контроля движений​

Поле `info` содержит результаты анализа движений в виде списка действий и их вердиктов.

    {
      "info": {
        "motion_control_result": [
          {
            "result": true,
            "pattern": "right"
          },
          {
            "result": true,
            "pattern": "left"
          },
          {
            "result": true,
            "pattern": "left"
          }
        ]
      }
    }

Поле | Описание
--- | ---
`result` | Вердикт выполнения действия (`true` — выполнено, `false` — не выполнено).
`pattern` | Название действия. Возможные значения: `up` (вверх), `left` (влево), `right` (вправо), `closer` (ближе), `farther` (дальше).

### Тип контента 3 — референсный кадр​

Поле `info` содержит результаты обработки референсного кадра биометрическими алгоритмами.

    "info": {
      "angles": [0, -2],
      "image_info": {
        "quality": { "value": true, "failed_checks": null },
        "deepfake": { "confidence": 0.00021070241928100586 },
        "liveness": {
          "value": "real",
          "confidence": 0.9773591756820679,
          "attack_type": "none",
          "attack_type_scores": { ... }
        }
      },
      "frame_number": 128
    }

Поле | Описание
--- | ---
`quality.value` | Вердикт алгоритма оценки качества (`true` — качество приемлемо).
`quality.failed_checks` | Список проваленных проверок качества (если есть).
`deepfake.confidence` | Уверенность алгоритма в наличии признаков дипфейка. Чем ниже значение, тем лучше.
`liveness.value` | Вердикт алгоритма живости: `"real"` — живой человек.
`liveness.confidence` | Уверенность алгоритма, что на фото живой человек. Чем выше, тем лучше.
`liveness.attack_type` | Распознанный тип атаки (`"none"` — атаки нет).
`liveness.attack_type_scores` | Уверенность алгоритма по каждому типу атаки.

### Тип контента 5 — верификационный кадр​

Поле `info` содержит результаты сравнения референсного кадра с кадром из веб-компоненты.

    {
      "info": {
        "verification_info": {
          "fa_r": 0,
          "fr_r": 0.6750852465629578,
          "score": 0.9856855273246765,
          "distance": 2339
        }
      }
    }

Поле | Описание
--- | ---
`score` | Уверенность алгоритма в совпадении лиц. Чем выше значение, тем выше вероятность, что лица принадлежат одному человеку.