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