Обзор

Все запросы REST API должны отправляться на https://api.facematica.vocord.ru/v1/.
Обязательно использование HTTPS для защиты пользовательских данных.
Для выполнения любых запросов необходимо получить API_KEY и привязать его своей учетной записи.
Метод входа /v1/account/login принимает API_KEY и возвращает токен доступа.
Токен доступа должен быть представлен в заголовке «Авторизация» для выполнении любых методов API.
Срок действия токена доступа ограничен. По истечении срока действия клиенты должны снова выполнить процедуру входа в систему.

Параметры представлены в виде строки запроса, то есть добавляются в URL-адреса запроса. Все ответы возвращаются в формате JSON и кодировке UTF-8.

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

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

API сгруппирован по следующим разделам:

  • Учетная запись и аутентификация
  • Лица и детектирование
  • Альбомы и распознавание

Раздел «Учетная запись и аутентификация» содержат методы аутентификации пользователя и доступа к токенам для всех остальных методов API.

Раздел «Лица и детектирование» предоставляет методы для обнаружения лиц на изображении и сопоставления обнаруженных лицам. Результатом детектирования (см. /v1/face/detect post-запрос) является набор дескрипторов лица, содержащий геометрические координаты лица на фотографии. Каждому лицу присваивается уникальный идентификатор (faceid), который можно использовать для доступа к информации о лицах и к оригинальному изображению. Обнаруженные лица и исходные изображения хранятся в «пуле детектирования» в течение ограниченного времени (72 часа), если он не был добавлен ни к одному альбому (см. раздел «Альбомы и распознавание»).
Атрибуты лица:

  • "faceid": уникальный идентификатор лица, сгенерированный методом детектирования. faceid присваивается любому лицу, обнаруженному на изображении. Каждое изображение может содержать несколько Лиц(Face). Каждому Лицу назначается уникальный faceid,
  • "img": уникальный идентификатор изображения, генерируемый методом детектирования. Все лица, обнаруженные на одном и том же изображении, имеют одинаковый идентификатор изображения. Изображение можно загрузить из пула детектирования get-методом /v1/ face/{faceid}/img. Атрибуты изображения могут быть получены get-методом /v1/face/{faceid}/img/info,
  • "x": x-координата центра линии глаз,
  • "y": y-координата центра линии глаз,
  • "angle": угол линии глаз,
  • "width": ширина линии глаз,

Список всех детектированных лиц может быть получен get-методом /v1/face/list. Метод может, потенциально, возвращать большой объем данных. Чтобы избежать возможных проблем, мы поддерживаем пейджинг (размер страницы и страница могут быть указаны как необязательные параметры в строке запроса; должно быть возвращено общее количество страниц).
Для нахождения соответствий заданному лицу в списке детектированных лиц («матчинга») должен быть сделан post-запрос /v1/face/ {faceid}/match. Он вычисляет коэффициент соответствия для каждого лица из заданного набора и основного лица по пути URL.
Типичный процесс работы:

  1. Детектирование лиц на изображениях,
  2. Поиск заданного лица по списку других лиц.

Раздел «Альбомы и распознавание» предназначен для управления альбомами лиц и поиска наиболее точно совпадающих лиц в альбомах. Этот раздел можно использовать после детектирования (см. раздел «Лица и детектирование»).
Пользователь может создать новый альбом с заданным именем и списком детектированных лиц по post-запросу /v1/album/new и добавлять в него лица позже по запросу /v1/album/{name}. Альбом и каждое лицо могут иметь дополнительные атрибуты. Атрибуты альбома могут быть установлены при создании альбома или по post-запросу /v1/album/{name}. Атрибуты лица могут быть добавлены при добавлении лица к альбому или позже по post-запросу /v1/album/{name}/{faceid}.
Можно просмотреть все альбомы, созданные пользователем, с помощью get-метода /v1/album/list и получить список всех лица в альбоме get-методом /v1/album/ {name}.
Для удаления альбома или указанных лиц в альбоме вызовите метод /v1/album/{name}[/faces:*.}].
Основной метод Раздела - поиск в галерее лиц, в наибольшей степени коррелирующих с заданным лицом. Метод /v1/album/recognize обеспечивает сравнивает все лица из галереи с заданным в URL лицом и возвращает список, отсортированный по степени совпадения. Длина списка задается количеством лиц и пороговым значением коэффициент совпадения
Типичный процесс работы:

  1. Подготовка
    • Детектирование лиц на эталонных изображениях.
    • Создание альбома из детектированных лиц или управление уже существующим альбомом.
  2. Основной цикл
    • Детектирование лица на заданном изображении
    • Распознавание лица по содержимому альбома

Успешная обработка и отчеты об ошибках
В случае успешной отработки запроса всегда возвращается HTTP-код 200 ОК. В случае ошибки всегда возвращается HTTP-код, отличный от 200 и JSON, содержащий код ошибки и описание.

  • ErrorCode – код ошибки.
  • ErrorMessage – понятное для человека описание ошибки, которое не должно обрабатываться автоматически. Может отличаться для одного и того же кода в зависимости от вызванного метода.

Некоторые коды ошибок:
400 (Bad Request ): Some of the parameters are invalid (Некоторые из параметров недействительны). ErrorMessage описывает, какой именно параметр вызвал ошибку.
401 (Unauthorized): Wrong authentication token or no token at all is provided (Неверный токен аутентификации или токен не указан).

Квоты на хранение (на одну учетную запись):

  • Количество альбомов: 100
  • Количество лиц, хранящихся на сервере: 50000

Ограничения:

  • Форматы изображений: JPEG, PNG
  • Максимальный размер файла с фото: 10 MB
  • Максимальное разрешение фото: 4,000 пикселей по длинной стороне
  • Минимальное расстояние между зрачками: 25 пикселей
  • Максимальное количество детектируемых лиц на одной фотографии: не ограничено

Ознакомиться с API полностью