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

In this section:

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

All REST API requests should be sent to http://<facenapi_ip>:8000/v1/.

Версия API

The API version is increased every time a major change is made and allows us to avoid breaking backwards compatibility. The API version should be specified in the request path (for example, v1 in /v1/detect/).

The most recent version is v1 which provides such advanced functions as gender, age and emotions recognition.

Примечание

When starting a new project, you should always use the latest stable version of the API.

Авторизация

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

Примечание

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

Authorization: Token yfT8ftheVqnDLS3Q0yCiTH3E8YY_cm4p

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

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

Лицо

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

  • "id" (number): unique identifier of the face generated by API.
  • "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.

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

Examples in methods descriptions illustrate possible method requests and responses. To check the examples without writing code, use the embedded API framework. To access the framework, enter in the address bar of your browser: http://<facenapi_ip>:8000/v1/docs/v1/overview.html for the API version /v1.

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

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

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

  • Strict (0.7834): used for applications where a chance of misidentification should be minimized. This level corresponds to False Accept Rate (FAR) of 1e-5 on our test dataset.
  • Medium (0.6616): balances low probability of misidentification and inability to identify a valid person. Corresponds to 1e-3 FAR on our test dataset.
  • Low (0.5690): used when it’s important to maximize the verification or identification rate, and misidentification does not cause severe consequences. Corresponds to 1e-1 FAR on our test dataset.
  • None (0): use when you need to calculate similarity of different persons or find similar people rather than verify identity.

You can also specify your own threshold level from 0 to 1, depending on your environment and needs.

Примечание

If no threshold level is specified, it is set to the default value 0.75.

Ограничения

FindFace Enterprise Server SDK imposes the following limits.

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

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

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

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

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

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

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