# Сравнение лиц

Сервис может подтвердить или опровергнуть факт: вот этот документ принадлежит вот этому человеку. На одном изображении должно быть лицо человека, а на втором — документ, удостоверяющий его личность. Документ мы рекомендуем брать из ответа сервиса «[Классификация документов](https://doc.dbrain.io/servisy/document-classification)». Сервис сравнивает лицо человека с фотографией из документа и даёт оценку их схожести. Можно ли использовать сервис в других бизнес-сценариях? Пожалуйста.

Если на изображении несколько лиц, сервис выберет лицо, которое занимает б**о**льшую площадь кадра, так что фото с друзьями и котами не возбраняются. Помимо сравнения лиц сервис сообщает дополнительную информацию о положении головы, глазах и рте.

{% hint style="success" %}
Чтобы воспользоваться сервисом, отправьте POST-запрос на URL <https://latest.dbrain.io/v2/face/distance>
{% 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

Сервис ожидает два изображения в атрибутах `image1` и `image2`.

#### Изображение

{% hint style="success" %}
**image1 — string ($binary)**

**image2 — string ($binary)**
{% endhint %}

Оба изображения обязательны для передачи в запросе. Сервис ожидает изображение в двоичном виде.

{% hint style="info" %}
Перед началом работы с сервисами изучите раздел [«Общая информация о сервисах»](https://doc.dbrain.io/obshaya-informaciya/obshaya-informaciya-o-servisakh). Там мы рассказываем про допустимые форматы файлов, виды запросов и ответов, набор HTTP-статусов и даём рекомендации по устранению ошибок
{% endhint %}

## В ответе на запрос API:

<details>

<summary>Иллюстрация к понятиям yaw, pitch и roll</summary>

<img src="https://content.gitbook.com/content/P798bs8GrIKSCwO6P0xF/blobs/5epuqjsU3Y9wMOGJaQaT/pitch-roll-yaw.png" alt="" data-size="original">

</details>

* `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, чем больше число, тем сильнее различаются лица
  * `warnings` — массив, описывающий предупреждения и ошибки, возможные значения:
    * More than one face detected on image 1 — найдено более 1 лица на изображении 1
    * More than one face detected on image 2 — найдено более 1 лица на изображении 2
    * No face detected on image1 — лицо не найдено на изображении 1
    * No face detected on image2 — лицо не найдено на изображении 2
    * Head yaw is too high on image 1 — поворот головы относительно вертикальной оси превышает ±5 градусов (здесь и далее ISO/IEC 19794-5) на изображении 1
    * Head yaw is too high on image 2 — поворот головы относительно вертикальной оси превышает ±5 градусов (здесь и далее ISO/IEC 19794-5) на изображении 2
    * Head pitch is too high on image 1 — наклон головы вверх или вниз относительно горизонтальной оси, проведённой через уши превышает ±5 градусов на изображении 1
    * Head pitch is too high on image 2 — наклон головы вверх или вниз относительно горизонтальной оси, проведённой через уши, превышает ±5 градусов на изображении 2
    * Head roll is too high on image 1 — наклон головы налево или направо относительно горизонтальной оси, проведённой через нос, превышает ±5 градусов на изображении 1
    * Head roll is too high on image 2 — наклон головы налево или направо относительно горизонтальной оси, проведённой через нос, превышает ±5 градусов на изображении 2
    * Left eye closed on image 1 — левый глаз закрыт на изображении 1
    * Left eye closed on image 2 — левый глаз закрыт на изображении 2
    * Left eye occluded on image 1 — левый глаз заслонён более, чем на 5% на изображении 1
    * Left eye occluded on image 2 — левый глаз заслонён более, чем на 5% на изображении 2
    * Right eye closed on image 1 — правый глаз закрыт на изображении 1
    * Right eye closed on image 2 — правый глаз закрыт на изображении 2
    * Right eye occluded on image 1 — правый глаз заслонён более, чем на 5% на изображении 1
    * Right eye occluded on image 2 — правый глаз заслонён более, чем на 5% на изображении 2
    * Mouth occluded on image 1 — рот заслонён более, чем на 5% на изображении 1
    * Mouth occluded on image 2 — рот заслонён более, чем на 5% на изображении 2
  * `same_face` — boolean, бинарный признак схожести лиц на двух изображениях
    * `true` — если distance меньше или равен 0.4
    * `false` — если distance больше 0.4
  * `faces1` и `faces2` — объекты, содержащие информацию о лице с изображения 1 и изображения 2 соответственно:
    * `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 — рот полностью закрыт
* `input_image1` — $string, [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) с MIME-типом JPEG в формате base64 — оригинал изображения номер 1, возвращается, если в запросе передать `return_crops=true`
* `input_image2` — $string, [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) с MIME-типом JPEG в формате base64 — оригинал изображения номер 2, возвращается, если в запросе передать `return_crops=true`

{% hint style="info" %}
Остальные поля не несут практического смысла. Оставили их для совместимости со старыми версиями
{% endhint %}