# Селфи-чек Сервис предназначен для обработки селфи с документами — фотографии, где видно и лицо человека, и документ, который он держит в руках. Дополнительно сервис проверяет, что человек предоставил именно главный разворот паспорта РФ, а также сообщает дополнительную информацию о положении головы, глазах и рте. {% hint style="success" %} Чтобы воспользоваться сервисом, отправьте POST-запрос на URL {% endhint %} ## Параметры запроса к сервису #### Асинхронный запрос {% hint style="success" %} #### async — boolean {% endhint %} Поведение по умолчанию: `async=false` — сервис обрабатывает запросы синхронно. При отправке запроса вы получите ответ только после окончательного завершения обработки запроса сервисом. Если вам нужен асинхронный режим, укажите в запросе `async=true`. В ответ на запрос сервис вернёт в `response body` параметр `task_id`. Например: ```json "task_id": "96b8ccc950a70699927036842c624d7c" ``` Используйте этот `task_id`, чтобы получить результаты классификации в методе `result`: ```bash curl -X 'GET' \ 'https://latest.dbrain.io/result/96b8ccc950a70699927036842c624d7c?token=XXX' \ -H 'accept: application/json' ``` Не забудьте указать в параметре `token` ваш ключ лицензии. Рекомендуем запрашивать метод `result` в цикле с периодом 1-2 секунды. #### Возврат найденных областей изображения {% hint style="success" %} **return\_crops — boolean** {% endhint %} Поведение по умолчанию: `return_crops=false` — cервис не возвращает найденные области изображения. Если вам нужны найденные сервисом области изображения, укажите `return_crops=true.` Сервис вернёт в ответе API в параметре crop найденные области изображения с лицами. #### Тегирование запроса {% hint style="success" %} **task\_tags — string array** {% endhint %} Поведение по умолчанию: параметр не используется. Функция тегирует запросы по вашему усмотрению. Это упрощает отслеживание пакетов документов, связанных с конкретным клиентом-физлицом. Для использования функции укажите в параметре `task_tags` удобный вам тег: `task_tags=тэг` ## Тело запроса к API #### Изображение {% hint style="success" %} **image — string ($binary)** {% endhint %} Изображение обязательно для передачи в запросе. Сервис ожидает изображение в двоичном виде. {% hint style="info" %} Перед началом работы с сервисами изучите раздел [«Общая информация о сервисах»](https://doc.dbrain.io/dbrain-official/obshaya-informaciya-o-servisakh). Там мы рассказываем про допустимые форматы файлов, виды запросов и ответов, набор HTTP-статусов и даём рекомендации по устранению ошибок {% endhint %} ## В ответе на запрос API:
Иллюстрация к понятиям yaw, pitch и roll
* `task_id` — string, идентификатор запроса, формат: 32 символа, 16-ричная строка * `error` — string, текстовое описание ошибки * `task_tags` — array\[string], теги, если они переданы в параметре task\_tags * `success` — boolean, статус запроса * `true` — запрос выполнен успешно * `false` — запрос не выполнен * `status_code` — integer, HTTP-код статуса запроса * 200 — запрос выполнен успешно * 400, 403, 500 и т.д. — расшифрованы в «[общей информации о сервисах](https://docs.dbrain.io/obshaya-informaciya-o-servisakh#http-kody-otveta-na-zapros)» * `items` — массив, содержащий смысловую часть ответа сервиса * `distance` — number от 0 до 1, чем больше число, тем сильнее различаются лица * `same_face` — boolean, бинарный признак схожести лиц на двух изображениях * `true` — если distance меньше или равен 0.6 * `false` — если distance больше 0.6 * `warnings` — массив, описывающий предупреждения и ошибки, возможные значения: * More than two face detected — найдено более 2 лиц * No face detected on image — лицо вне документа не найдено * No face photo detected in document — фотография с лицом в документе не найдена * No document detected on image — на изображении не найден документ * Document type doesn't match requested — найденный тип документа не соответствует главному развороту паспорта РФ * Head yaw is too high — поворот головы относительно вертикальной оси превышает ±5 градусов (здесь и далее ISO/IEC 19794-5) * Head pitch is too high — наклон головы вверх или вниз относительно горизонтальной оси, проведённой через уши, превышает ±5 градусов * Head roll is too high — наклон головы налево или направо относительно горизонтальной оси, проведённой через нос, превышает ±5 градусов * Left eye closed — левый глаз закрыт * Left eye occluded — левый глаз заслонён более, чем на 5% * Right eye closed — правый глаз закрыт * Right eye occluded — правый глаз заслонён более, чем на 5% * Mouth occluded — рот заслонён более, чем на 5% * `faces` и `faces_on_document` — объекты, содержащие информацию о лице человека и о лице с фотографии в документе соответственно: * `confidence` — number от 0 до 1, уровень уверенности модели, что на изображении найдено именно лицо, а не что-то другое * `coords` — массив, координаты лица на изображении по четырём точкам: верхний левый угол, верхний правый, нижний левый, нижний правый * `crop` — $string, [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) с MIME-типом JPEG в формате base64, область изображения с найденным лицом, возвращается, если в запросе передать `return_crops=true` * `rotation` — integer, в котором закодирована ориентация лица * 0 — поворот не требуется * 1 — требуется поворот на 90 градусов * 2 — требуется поворот на 180 градусов * 3 — требуется поворот на 270 градусов * `head` — объект, содержащий оценку положения головы в трёх измерениях * `pitch` — number от -180 до 180: оценка наклона головы вверх или вниз относительно горизонтальной оси, проведённой через уши, где 0 — нет наклона. * `yaw` — number от -180 до 180: оценка поворота головы налево или направо относительно вертикальной оси, где 0 — нет поворота. * `roll` — number от -180 до 180: оценка наклона головы налево или направо относительно горизонтальной оси, проведённой через нос, где 0 — нет наклона. * `left_eye` — объект, содержащий оценку левого глаза * `occluded` — number от 0 до 1, где 0 — глаз ничем не заслонён, а 1 — глаз полностью заслонён * `open` — true/false, где true — глаз открыт * `right_eye` — объект, содержащий оценку правого глаза * `occluded` — number от 0 до 1, где 0 — глаз ничем не заслонён, а 1 — глаз полностью заслонён * `open` — true/false, где true — глаз открыт * `mouth` — объект, содержащий оценку рта * `occluded` — number от 0 до 1, где 0 — рот ничем не закрыт, а 1 — рот полностью закрыт * `document` — объект, содержащие информацию о документе на изображении, из которого сервис взял фотографию для сравнения * `confidence` — number от 0 до 1, уровень уверенности модели, что на изображении найдено именно лицо, а не что-то другое * `coords` — массив, координаты документа на изображении по четырём точкам: верхний левый угол, верхний правый, нижний левый, нижний правый * `crop` — $string, [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) с MIME-типом JPEG в формате base64, область изображения с найденным лицом, возвращается, если в запросе передать `return_crops=true` * `rotation` — integer, в котором закодирована ориентация лица * 0 — поворот не требуется * 1 — требуется поворот на 90 градусов * 2 — требуется поворот на 180 градусов * 3 — требуется поворот на 270 градусов * `type` — string, тип найденного на изображении документа согласно [списку поддерживаемых документов](https://doc.dbrain.io/dbrain-official/tipy-dokumentov) * `input_image` — $string, [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) с MIME-типом JPEG в формате base64 — оригинал изображения номер 1, возвращается, если в запросе передать `return_crops=true` {% hint style="info" %} Остальные поля не несут практического смысла. Оставили их для совместимости со старыми версиями {% endhint %}