Как пользоваться 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