Как пользоваться API для анализа и распознавания биометрических данных

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

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

Все запросы HTTP API для анализа и распознавания биометрических данных нужно отправлять на адрес http://<IP адрес findface-sf-api>:18411/. Запросы выполняются компонентом findface-sf-api.

Версия API

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

На данный момент самой последней версией API является v2.

Совет

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

Лицо как объект API

API для анализа и распознавания биометрических данных оперирует объектом лицо, представляющим собой изображение человеческого лица.

Примечание

На фотографии может быть несколько лиц и, следовательно, несколько ассоциированных с ней объектов лицо.

Примечание

Разные изображения одного и того же человека рассматриваются как разные объекты лицо.

Объект лицо имеет следующие атрибуты:

  • ”id” (uint64): (только если лицо добавлено в биометрическую базу данных) пользовательский идентификатор лица (uint64), задается в API-запросе при добавлении лица из memcached в базу данных Tarаntool. Идентификатор передается как <id> в методе /galleries/<gallery>/faces/<id> POST.
  • "facen" (байты): биометрический образец, вектор признаков, извлеченный из лица.
  • "meta" (строка): набор строк с метаданными, который может быть использован для хранения любой связанной с лицом информации (например, имени человека, id видеокамеры, даты и времени обнаружения и пр.).
  • "features" (словарь): словарь, ключом в котором выступает строка, а значение может быть любого типа. Используется для хранения таких биометрических параметров лица, как пол, возраст, эмоции и др.

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

Существует два способа передать фотографию в систему:

  • как публичный адрес в сети Интернет,
  • в виде файла.

Существуют следующие способы передачи параметров в методы HTTP API для анализа и распознавания биометрических данных:

  • image/jpeg, image/png, image/webp: для передачи изображения в виде файла,
  • text/x-url: для передачи изображения в виде URL,
  • query string: параметры добавляются в конец URI запроса.

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

Как пользоваться примерами

Примеры в описаниях методов иллюстрируют возможные запросы и ответы метода. Для проверки примеров без написания кода используйте встроенный API-фреймворк. Для перехода в него введите в адресной строке браузера http://<findface-sf-api_ip>:18411/v2/docs/v2/overview.html для API версии /v2.

Ограничения

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

Параметр Значение
Формат изображения JPG, PNG, WEBP, BMP
Максимальный размер файла Настраивается в файле конфигурации компонента findface-sf-api.
Минимальный размер лица 50x50 пикселей
Максимальное количество обнаруженных лиц на 1 изображение Не ограничено

Важно

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

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

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

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

Полный список ошибок

Код ошибки Описание Код HTTP
UNKNOWN_ERROR Ошибка неизвестного происхождения. 500
BAD_PARAM Запрос может быть прочитан, однако некоторые параметры метода недействительны. Данный тип ответа содержит дополнительные атрибуты param и value для описания ошибочных параметров. 400
CONFLICT Конфликт. 409
EXTRACTION_ERROR Ошибка при извлечении из лица вектора признаков. 503
LICENSE_ERROR Конфигурация системы не соответствует лицензии. 503
MALFORMED_REQUEST Запрос неправильно сформирован и не может быть прочитан. 400
OVER_CAPACITY Превышен размер очередей в компоненте findface-extraction-api. 429
SOURCE_NOT_FOUND В параметре from задано несуществующее лицо. 400
SOURCE_GALLERY_NOT_FOUND В параметре from задана несуществующая галерея. 400
STORAGE_ERROR Биометрическая база данных недоступна. 503
CACHE_ERROR Хранилище memcached недоступно. 503
NOT_FOUND Подходящие лица не найдены. 404
NOT_IMPLEMENTED Функционал не реализован. 501
GALLERY_NOT_FOUND Подходящие галереи не найдены. 404