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

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

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

{% 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" %}
Перед началом работы с сервисами изучите раздел [«Общая информация о сервисах»](/dbrain-official/obshaya-informaciya-o-servisakh.md). Там мы рассказываем про допустимые форматы файлов, виды запросов и ответов, набор HTTP-статусов и даём рекомендации по устранению ошибок
{% endhint %}

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

<details>

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

<img src="/files/ovHA3rwn2uDGpnw1TxDG" 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.dbrain.io/dbrain-official/operacii-s-licami/sravnenie-lic.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.