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

Сравниваем лица на двух изображениях и даём оценку их схожести

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

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

Чтобы воспользоваться сервисом, отправьте POST-запрос на URL https://latest.dbrain.io/v2/face/distance

Параметры запроса к сервису

Асинхронный запрос

async — boolean

Поведение по умолчанию: async=false — сервис обрабатывает запросы синхронно. При отправке запроса вы получите ответ только после окончательного завершения обработки запроса сервисом.

Если вам нужен асинхронный режим, укажите в запросе async=true. В ответ на запрос сервис вернёт в response body параметр task_id. Например:

"task_id": "96b8ccc950a70699927036842c624d7c"

Используйте этот task_id, чтобы получить результаты классификации в методе result:

curl -X 'GET' \
  'https://latest.dbrain.io/result/96b8ccc950a70699927036842c624d7c?token=XXX' \
  -H 'accept: application/json'

Не забудьте указать в параметре token ваш ключ лицензии. Рекомендуем запрашивать метод result в цикле с периодом 1-2 секунды.

Возврат найденных областей изображения

return_crops — boolean

Поведение по умолчанию: return_crops=false — cервис не возвращает найденные области изображения.

Если вам нужны найденные сервисом области изображения, укажите return_crops=true. Сервис вернёт в ответе API в параметре crop найденные области изображения с лицами.

Тегирование запроса

task_tags — string array

Поведение по умолчанию: параметр не используется.

Функция тегирует запросы по вашему усмотрению. Это упрощает отслеживание пакетов документов, связанных с конкретным клиентом-физлицом. Для использования функции укажите в параметре task_tags удобный вам тег: task_tags=тэг

Тело запроса к API

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

Изображение

image1 — string ($binary)

image2 — string ($binary)

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

Перед началом работы с сервисами изучите раздел «Общая информация о сервисах». Там мы рассказываем про допустимые форматы файлов, виды запросов и ответов, набор HTTP-статусов и даём рекомендации по устранению ошибок

В ответе на запрос 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 и т.д. — расшифрованы в «общей информации о сервисах»
• 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 с 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 с MIME-типом JPEG в формате base64 — оригинал изображения номер 1, возвращается, если в запросе передать return_crops=true
• input_image2 — $string, data URL с MIME-типом JPEG в формате base64 — оригинал изображения номер 2, возвращается, если в запросе передать return_crops=true

Остальные поля не несут практического смысла. Оставили их для совместимости со старыми версиями