Как пользоваться REST API

В этом разделе:

Точка доступа

Все запросы REST API должны быть отправлены на адрес http://<facenapi_ip>:8000/v1/.

Версия API

Версия API обновляется каждый раз при больших изменениях функционала, при этом новые версии, как правило, совместимы с прежними версиями FindFace Enterprise Server SDK. Версия API указывается в пути запроса (например, v1 в /v1/detect/).

На данный момент самой последней версией API является v1, обеспечивающая такие передовые функции, как распознавание пола, возраста и эмоций.

Примечание

При запуске нового проекта должна всегда использоваться последняя стабильная версия API.

Авторизация

Для всех методов API должна быть выполнена простая HTTP-авторизация на базе токена. Для того чтобы авторизовать запрос, после заголовка Authorization нужно добавить метку Token и ввести через пробел свой токен авторизации:

Примечание

См. Создание токена авторизации.

Authorization: Token yfT8ftheVqnDLS3Q0yCiTH3E8YY_cm4p

Если запрос не содержит действительный токен, результатом его выполнения будет являться ответ HTTP 401 Unauthorized.

Распространенные типы объектов

Лицо

Представляет собой изображение человеческого лица. Имейте в виду, что на одной фотографии может быть несколько лиц. Разные изображения одного и того же человека также рассматриваются как разные лица.

  • "id" (число): уникальный идентификатор лица, генерируемый Сервером.
  • "timestamp" (строка): время создания объекта лицо в формате ISO8601.
  • "photo" (строка): URL или имя файла с изображением, которое было использовано для создания объекта лицо.
  • "photo_hash" (строка): хэш исходной фотографии. Имейте в виду, что хэш идентичных фотографий будет одинаков, в то время как разные фотографии с большой вероятностью будут иметь разный хэш. Данный параметр не подлежит интерпретированию.
  • "thumbnail" (строка): URL миниатюры лица, хранящейся на Сервере.
  • "x1" (число): координата x левого верхнего угла прямоугольника с лицом (рамки) на исходной фотографии.
  • "y1" (число): координата y левого верхнего угла прямоугольника с лицом (рамки) на исходной фотографии.
  • "x2" (число): координата x нижнего правого угла прямоугольника с лицом (рамки) на исходной фотографии.
  • "y2" (число): координата y нижнего правого угла прямоугольника с лицом (рамки) на исходной фотографии.
  • "meta" (строка): строка с метаданными, которая может быть использована для хранения любой связанной с лицом информации (например, имени человека).
  • "galleries" (string[]): массив имен галерей, в которых хранится лицо.

Рамка

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

  • Список координат со значениями:
    • «x1» (число): координата x левого верхнего угла прямоугольника с лицом;
    • «y1» (число): координата y левого верхнего угла прямоугольника с лицом;
    • «x2» (число): координата x нижнего правого угла прямоугольника с лицом;
    • «y2» (число): координата y нижнего правого угла прямоугольника с лицом.
  • Линейно: [x1, y1, x2, y2].

В API-запросах можно использовать оба формата, однако независимо от того, какой формат был использован, запрос вернет координаты рамки в представлении JSON.

Имейте в виду, что рамка может выходить за физические границы фотографии, включая отрицательные значения координат.

Формат Параметров

Существуют следующие способы передачи параметров в методы API:

  • application/json: в формате JSON в теле запроса.
  • application/x-www-form-urlencoded: с использованием имен полей формы и значений этих полей.
  • multipart/form-data: параметры кодируются несколькими частями. Данный способ поддерживает загрузку фотографии в том же запросе.
  • query string: параметры добавляются в конец URI запроса. При передаче параметров этим способом сложные структуры, такие как координаты рамок, должны быть представлены в формате JSON.

Существует два способа задать файл с изображением:

  • как публичный адрес в сети Интернет (прямой, без переадресации),
  • включить в запрос в составе multipart/form-data.

Все ответы отправляются в формате JSON и кодировке UTF-8.

Использование примеров из документации

Примеры в описаниях методов иллюстрируют возможные запросы с этими методами и соответствующие ответы. Для проверки примеров нет необходимости писать код. Достаточно использовать встроенный в FindFace Enterprise Server SDK API-фреймворк. Для доступа к фреймворку введите в адресной строке браузера: http://<facenapi_ip>:8000/v1/docs/v1/overview.html for the API version /v1.

Пороговая схожесть лиц при верификации и идентификации

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

Существует 4 предустановленных порога:

  • Strict (0.7834): используется в проектах, в которых вероятность ложного пропуска (положительной верификации) должна быть минимизирована. Данный уровень соответствует вероятности ложного пропуска 1e-5 в системе False Accept Rate (FAR) при тестировании на нашей базе данных.
  • Medium (0.6616): низкая вероятность как ложного пропуска, так и ложного отказа в доступе. Соответствует вероятности 1e-3 FAR.
  • Low (0.5690): используется в проектах, в которых важно уменьшить ложный отказ в доступе, а ложный пропуск не несет за собой серьезных последствий. Соответствует вероятности 1e-1 FAR.
  • None (0): используется, когда нужно рассчитать степень схожести разных людей, а не проверить идентичность.

Вы также можете задать собственное пороговое значение в зависимости от ваших нужд.

Примечание

Если параметр threshold не передан, его значение по умолчанию устанавливается равным 0.75.

Ограничения

Для FindFace Enterprise Server SDK актуальны следующие ограничения.

Параметр Значение
Формат изображения JPEG, PNG, WEBP
Максимальный размер файла 10 MБ
Минимальный размер лица 50x50 пикселей
Максимальное количество лиц на изображении Не ограничено

В дополнение к этому, URL изображения должен быть публичным (не требующим авторизации) и прямым (без перенаправлений).

Сообщения об ошибках

Если метод выполнить не удается, Сервер возвращает ответ с кодом HTTP, отличном от 200, а также тело ответа в формате JSON, содержащее описание ошибки. Тело ответа всегда содержит хотя бы 2 поля — code и status:

  • code — это код ошибки, который может быть использован для автоматического преобразования;
  • reason — это описание ошибки, предназначенное для прочтения человеком, а не для автоматического преобразования.

Распространенные коды ошибок представлены в таблице ниже:

Код ошибки Описание
AUTH_FAILED Неверный токен авторизации или токен не был предоставлен.
BAD_PARAM Некоторые параметры метода недействительны. Данный тип ответа содержит дополнительные атрибуты параметр и значение для описания ошибочных параметров.
MALFORMED_JSON Тело запроса содержит неверно сформированный JSON.
SERVICE_UNAVAILABLE Запрос не может быть обработан из-за недоступности некоторых компонентов Сервера.