Как пользоваться 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
.
Разбиение по страницам¶
Некоторые методы (такие как GET /faces/
и GET /meta/
) могут возвращать тысячи, если не сотни тысяч результатов. Для того чтобы избежать связанных с этим проблем, Сервер возвращает результаты с разбиением по страницам.
Методы, поддерживающие разбиение по страницам, возвращают в дополнение к результатам еще 2 параметра:
prev_page
: адрес предыдущей страницы (содержит только путь метода и указатель предыдущей порции результатов).next_page
: адрес следующей страницы (содержит только путь метода и указатель следующей порции результатов).
Таким образом, если метод GET http://<facenapi_ip>:8000/v0/faces/
вернул параметр next_page
со значением /v0/faces/?max_id=12345
, для получения следующей порции результатов необходим запрос GET http://<facenapi_ip:8000/v0/faces/?max_id=12345
.
Ограничения¶
Для 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 |
Запрос не может быть обработан из-за недоступности некоторых компонентов Сервера. |