Алгоритм определения живости предназначен для проверки наличия живого человека по короткому видео фрагменту.

Порядок действий:

1. Авторизуйтесь.

2. Поместите медиафайл в папку.

{
  "media:tags": {
    "video1": [
      "video_selfie",
      "video_selfie_scan",
      "orientation_portrait"
    ]
  }
}

3. Запустите анализ.

{
  "analyses": [{
    "type": "quality",
    "source_media": ["6187a4ef-62c4-4445-bbb2-bf62d61f1fde"],
  }]
}

В source_media указывается media_id из ответа предыдущего запроса. Это опционально, если требуется проверить одно из двух заранее загруженных в папку видео.

Сохраните analyse_id из ответа.

4а. Через некоторое время проверьте результат.

Дождитесь, когда поля resolution_status и resolution изменят статус на любой, кроме PROCESSING, – этот статус и будет результатом.

4б. Еще один вариант: добавьте вебхук, который обратится к вашему сайту по завершении анализа. В payload запроса добавьте нужный адрес в поле resolution_endpoint:

{    
    "resolution_endpoint": "address.com",
    {
    .... // информация о папке и т.д.
    }
}

В запросе вебхука будет содержаться информация о папке и связанных с ней анализах.

Подробно статусы анализов описаны здесь.

Алгоритм проверки по черному списку предназначен для проверки присутствия человека по базе заранее загруженных фотографий. В качестве источника для сравнения можно использовать изображение и/или фрагмент видео.

Порядок действий описан ниже.

1. Авторизуйтесь. Параметры передаются в json-запросе в составе credentials. См. статьи Коллекции Postman и Аутентификация.

2. Поместите видеофайл в папку, как описано здесь.

Пример заполнения payload для видео:

{
  "media:tags": {
    "video1": [
      "video_selfie",
      "video_selfie_scan",
      "orientation_portrait"
    ]
  }
}

3. Запустите анализ: POST/api/folders/{{folder_id}}/analyses/

В типе анализа должно быть указано collection.

{
    "analyses": [{
    "type": "collection",
    "source_media": ["идентификатор_медиафайла_источника"],
  }]
}

В source_media указывается media_id из ответа предыдущего запроса. Это опционально, если требуется проверить одно из двух заранее загруженных в папку видео.

Сохраните analyse_id из ответа.

4а. Через некоторое время проверьте результат. Дождитесь, когда поля resolution_status и resolution изменят статус на любой, кроме PROCESSING, – этот статус и будет результатом.

4б. Еще один вариант: добавьте вебхук, который обратится к вашему сайту по завершении анализа. В payload запроса добавьте нужный адрес в поле resolution_endpoint:

{    
    "resolution_endpoint": "address.com",
    {
    .... // информация о папке и т.д.
    }
}

В запросе вебхука будет содержаться информация о папке и связанных с ней анализах.

Подробно статусы анализов описаны здесь.

Если вы хотите узнать, с кем именно из вашей базы фотографий совпало лицо с медиафайла, который вы только что загрузили, найдите в ответе анализ collection, в нем results_media, где и будет идентификатор нужной вам персоны person_id. Чтобы получить информацию об этой персоне, вызовите метод GET /api/collections/{{collection_id}}/persons/{{person_id}}, указав идентификаторы вашей коллекции и персоны в ней.

Алгоритм "лучший кадр" выбирает из видеозаписи наиболее качественный и удачный кадр с лицом. Алгоритм вызывается дополнительно к анализу liveness.

Порядок действий:

1. Авторизуйтесь.

2. Поместите видеофайл в папку.

{
  "media:tags": {
    "video1": [
      "video_selfie",
      "video_selfie_scan",
      "orientation_portrait"
    ]
  }
}

3. Запустите анализ. Убедитесь, что параметр "extract_best_shot" имеет значение True, как показано ниже.

{
  "analyses": [{
    "type": "quality",
    "source_media": ["6187a4ef-62c4-4445-bbb2-bf62d61f1fde"],
    "params" : {
      "extract_best_shot": true
    }
  }]
}

В source_media указывается media_id из ответа предыдущего запроса. Это опционально, если требуется проверить одно из двух заранее загруженных в папку видео.

Сохраните analyse_id из ответа.

4а. Через некоторое время проверьте результат. Дождитесь, когда поля resolution_status и resolution изменят статус на любой, кроме PROCESSING, – этот статус и будет результатом.

4б. Еще один вариант: добавьте вебхук, который обратится к вашему сайту по завершении анализа. В payload запроса добавьте нужный адрес в поле resolution_endpoint:

{    
    "resolution_endpoint": "address.com",
    {
    .... // информация о папке и т.д.
    }
}

В запросе вебхука будет содержаться информация о папке и связанных с ней анализах.

Подробно статусы анализов описаны здесь.

5. Лучший кадр можно получить из ответа results_media -> output_images -> original_url

Аутентификация пользователя

Чтобы получить токены доступа, нужно выполнить POST-запрос на /authorize/auth/. В теле запроса нужно указать полученные от нас электронную почту и пароль в составе credentials, а также API-адрес в качестве адреса хоста.

Body

{
	"credentials": {
		"email": "{{user_email}}",
		"password": "{{user_password}}"
	}
}

Результатом аутентификации пользователя является пара access_token и expire_token.

access_token – ключ (набор символов), предъявление которого является пропуском к ресурсам системы. Обращение к ним происходит с указанием в заголовках полученного access_token.

headers = {‘ X-Forensic-Access-Token’: <access_token>}

Действие access_token ограничено во времени и регулируется настройками:

• для сервисных учетных записей – OZ_SESSION_LONGLIVE_TTL (по умолчанию 5 лет),

• для всех остальных – OZ_SESSION_TTL (по умолчанию 15 минут).

expire_token предназначен для обновления пары access_token и expire_token.

Автопродление сессий

если expire_date > текущей даты, то expire_date сессии устанавливается в значение текущей даты + временная дельта настроек, описанных выше.

Обновление токенов

Чтобы обновить пару access_token и expire_token, нужно выполнить POST-запрос на адрес authorize/refresh/ c expire_token в теле запроса и X-Forensic-Access-Token в заголовках.

{
    "expire_token": "{{expire_token}}"
}

Положительным результатом будет ответ с новой парой access_token и expire_token. Предыдущая пара access_token и expire_token будет удалена из базы данных при первой аутентификации по новой паре access_token и expire_token.

Возможные ошибки

Чтобы провести анализы для ваших медиафайлов, необходимо поместить их в папку – либо существующую, либо новую, созданную с помощью Oz API. Для каждого файла необходимо указать теги: они описывают, что это за файл и какие анализы к нему применимы.

Создание папки и добавление в нее медиафайлов: POST /api/folders/

Добавление файлов в существующую папку: POST /api/folders/{{folder_id}}/media/

Файлы должны быть добавлены в теле запроса, теги – в поле payload.

Пример заполнения payload для пассивного Liveness и фотографии лицевой стороны документа:

{
    "media:tags": { // здесь устанавливаются теги для загружаемых вами медиафайлов
    // media files are referenced by the keys in a multipart form
        "video1": [ // ключ для файла
        // стандартный набор тегов для видео с пассивным Liveness
            "video_selfie", // видео с лицом
            "video_selfie_blank", //  отсутствует
            "orientation_portrait" // ориентация видео
        ],
        "photo1": [
        // стандартный набор тегов для лицевой стороны документа
            "photo_id",
            "photo_id_front"
        ]
    }
}

Пример использования (Postman):

В случае успеха в ответе вернется информация о папке.

Liveness – проверка «живости», того, что человек, снятый на видео, действительно живой реальный человек в сознании.

Биометрия – сравнение двух или более лиц с различных фотографий или видеороликов с целью ценить степень их схожести (один и тот же это человек или разные люди).

Лучший кадр – выбор лучшего кадра из видеоролика для использования его в бизнес-процессах как результата Liveness-проверки, «видео в виде картинки».

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

Результаты анализов – получение результатов анализов через API в численной форме.

Информация о том, как интерпретировать результаты каждого анализа, содержится в статье Типы анализов.

Результат любого анализа представляет собой число. Для анализа Biometry это число отражает степень совпадения/несовпадения лиц в загруженных вами медиафайлах по сравнению с референсами – теми файлами, которые хранятся в базе. Для анализа Liveness – возможность того, что на загруженном медиафайле не реальный живой человек в сознании, а какое-то его изображение или deepfake. Результаты анализов можно узнать и без захода в каждую заявку по отдельности – API предоставляет возможность извлечь их из JSON-ответа.

1. .

2. Сделайте запрос к или . Параметр with_analyses должен быть установленTrue.

3. Для типа анализа Biometry ищите значение параметра min_confidence:

Этот параметр отражает уверенность системы в том, что на представленных медиа фигурирует один и тот же человек.

4. Для типа анализа Liveness Analysis ищите значение параметра confidence_spoofing для нужного медиафайла:

Этот параметр показывает вероятность спуфинг-атаки – того, что на полученном видео, например, использовалась технология deepfake или вместо человека программе показали видеоролик с этим человеком.

Если нужно обработать несколько результатов анализов, запросите список заявок и сделайте парсинг JSON-ответа.

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

Коллекция в Oz API – это база фотографий лиц (персон), которые используются в анализе Blacklist для сравнения с лицом человека с только что снятого фото или видео.

Персона – это сущность в коллекции, соответствующая одному человеку. Для одной персоны может быть загружено несколько фотографий.

Как создать коллекцию

Коллекция создается в рамках определенной компании, таким образом, для добавления новой коллекции необходим идентификатор компании company_id.

Если вы его не знаете, найдите компанию поиском с помощью метода GET /api/companies/?search_text=test, где test – наименование компании или его часть. Сохраните полученный company_id.

Для создания коллекции вызовите метод POST /api/collections/. В теле запроса укажите название своей коллекции (alias) и company_id нужной компании, как показано ниже:

В ответе на запрос будет идентификатор коллекции collection_id. Он понадобится на следующем шаге.

Как добавить персону или фото в коллекцию

Для добавления новой персоны в коллекцию вызовите метод POST /api/collections/{{collection_id}}/persons/, где collection_id – идентификатор коллекции из предыдущего шага. В запросе передайте фото персоны (или несколько фото). В Payload укажите соответствующие фото , как показано ниже.

В ответе вам придет идентификатор персоны person_id - это идентификатор отдельного человека в коллекции.

В этом же запросе через payload можно добавить данные о персоне:

Вы также можете загрузить дополнительные фото персоны после ее добавления: используйте метод POST {{host}}/api/collections/{{collection_id}}/persons/{{person_id}}/images/ с соответствующим person_id. Тело запроса заполните так же, как для метода POST /api/collections/{{collection_id}}/persons/.

Чтобы получить информацию о всех персонах в коллекции, вызовите метод GET /api/collections/{{collection_id}}/persons/.

Если вам нужен список фотографий для отдельной персоны, воспользуйтесь методом GET /api/collections/{{collection_id}}/persons/{{person_id}}/images/. Обратите внимание: для каждого фото будет указан идентификатор фото person_image_id – он потребуется вам, например, для удаления фото.

Как удалить фото или персону из коллекции

Чтобы удалить персону со всеми соответствующими ей фотографиями, используйте метод DELETE /api/collections/{{collection_id}}/persons/{{person_id}}, указав идентификаторы коллекции и персоны. Все фото этой персоны удалятся автоматически. Персону нельзя удалить, если с ней связаны анализы – то есть если эта персона участвовала в анализе Black list и с ней были найдены совпадения. Для удаления такой персоны сперва нужно удалить соответствующие анализы методом DELETE /api/analyses/{{analyse_id}} (потребуется analyse_id анализа collection (Black list)).

Для удаления всех связанных с коллекцией анализов запросите список всех папок с анализом Black list: call GET /api/folders/?analyse.type=COLLECTION. Для каждой папки из списка (GET /api/folders/{{folder_id}}/), найдите analyse_id нужного анализа, а затем удалите анализ – DELETE /api/analyses/{{analyse_id}}.

Для удаления определенной фотографии той или иной персоны вызовите метод DELETE /api/collections/{{collection_id}}/persons/{{person_id}}/images/{{person_image_id}} и укажите идентификаторы коллекции, персоны, фотографии.

Как удалить коллекцию целиком

Перед удалением коллекции нужно удалить информацию о всех входящих в нее персонах, а затем стереть саму коллекцию с помощью метода DELETE /api/collections/{{collection_id}}/.

Биометрический алгоритм позволяет сравнить несколько фотографий и оценить уровень схожести людей на них. В качестве источников проверки можно передавать фото, видео и документы (с фото).

Порядок действий:

1. .

2. .

Не указывайте source_media, если хотите провести анализ всех медиа в папке в соответствии с установленными им тегам.

Сохраните analyse_id из ответа.

Дождитесь, когда поля resolution_status и resolution изменят статус на любой, кроме PROCESSING, – этот статус и будет результатом.

В запросе вебхука будет содержаться информация о папке и связанных с ней анализах.

Описание

Oz API является центральным компонентом системы, который связывает между собой все остальные компоненты. В том числе:

• предоставляет единый Rest API для запуска Liveness и Biometry анализов

• ведет базу запросов и выполненных анализов

• архивирует входящие медиаданные

• собирает телеметрию с подключенных мобильных приложений

• предоставляет возможность настроить специфичные модели устройств

• генерирует подробные отчеты о результатах выполнения анализов

Описание основных методов Rest API схемы:

Коллекция Postman, включающая в себя все имеющиеся на данный момент методы:

В этом разделе вы найдете описание API.

Вебхуки (webhook) упрощают процесс получения результатов анализов. После запуска анализов не нужно инициировать опрос с проверкой, завершены ли анализы. Вместо этого в запросе на анализы добавьте вебхук, который обратится к вашему веб-сайту, когда результаты будут готовы.

При создании папки добавьте нужный веб-адрес (resolution_endpoint) в раздел payload в теле запроса:

Каждый раз, когда анализы для этой папки будут готовы, вам будет приходить уведомление. Вебхук-запрос будет содержать результаты анализов и информацию о папке, для которой они выполнялись.

Теги видеофайлов

Для видеофайлов в Системе должны быть указаны следующие типы тегов:

• Тег, определяющий тип данных «видео»:

  • video_selfie

• Тег, определяющий ориентацию видео:

  • orientation_portrait – портретная ориентация;

  • orientation_landscape – ландшафтная ориентация.

• Тег, определяющий действие на видео:

  • video_selfie_left – поворот головы налево;

  • video_selfie_right – поворот головы направо;

  • video_selfie_down – наклон головы вниз;

  • video_selfie_high – наклон головы вверх;

  • video_selfie_smile – улыбка;

  • video_selfie_eyes – моргание;

  • video_selfie_scan – сканирование;

  • video_selfie_oneshot – анализ по одному кадру;

  • video_selfie_blank – нет действия.

Важно: в версии API 4.0.8 или старше, чтобы отправить на анализ Quality (Liveness) изображение, а не видео, необходимо поместить его в архив .zip, установить тип файла SHOTS_SET и поставить один из тегов video_, иначе Quality изображение проигнорирует.

Пример корректного набора тегов видеофайла с действием «моргание»:

Теги фотофайлов

Для фотофайлов в Системе должны быть указаны следующие типы тегов:

• Тег для селфи:

  • photo_selfie – тег, определяющий тип фотографии «селфи»

• Теги для фотографий или сканов удостоверений личности:

  • photo_id – тег, определяющий тип фотографии «документы»;

  • photo_id_front – фото лицевой стороны документа;

  • photo_id_back – фото обратной стороны документа (любые другие анализы, кроме Документов, файлы с этим тегом игнорируют).

Важно: в версии API 4.0.8 или старше, чтобы отправить на анализ Quality (Liveness) изображение, а не видео, необходимо поместить его в архив .zip, установить тип файла SHOTS_SET и поставить один из тегов video_, иначе Quality изображение проигнорирует.

Пример корректного набора тегов фотофайла «селфи»:

Пример корректного набора тегов фотофайла с лицевой стороной документа:

Пример корректного набора тегов фотофайла с обратной стороной документа:

Анализы могут быть назначены медиафайлам как вручную пользователем – например, через выбор сценария Liveness в приложении – так и автоматически, когда выбор не производится и пользователь запускает все возможные анализы для папки с медиафайлами.

В последнем случае система автоматически определяет, какие именно анализы должны запускаться для того или иного медиафайла. При этом она исходит из того, какие указаны при загрузке файлов. Если файлы загружаются через web-консоль, теги расставляет пользователь, если ведется съемка через SDK – теги проставляются в процессе съемки также автоматически. Также роль играет тип медиафайлов: IMAGE (фото)/VIDEO/SHOTS_SET (приравнивается к видео). Если медиафайл не подходит под требования того или иного анализа, этот анализ такой медиафайл игнорирует.

Список настроек по умолчанию приведен ниже. Для изменения конфигурации, пожалуйста, .

Анализ выполняется для всех медиафайлов вне зависимости от воспроизводимого в них (теги жестов начинаются с video_selfie).

Внимание: в версии API 4.0.8 и ниже, чтобы отправить на анализ Quality (Liveness) изображение, а не видео, необходимо поместить его в архив .zip, установить тип файла SHOTS_SET и поставить один из тегов video_, иначе Quality изображение проигнорирует.

Анализ выполняется для всех фото и видео.

Если в папке будет менее двух подходящих медиафайлов, система вернет ошибку. Если более двух, то будут сравниваться все возможные пары, и система выдаст результат по паре с наименьшим сходством.

Анализ выполняется только при наличии заранее созданного черного списка для всех присутствующих в папке / указанных в качестве источника фото и видео.

Это дополнительная опция к анализу Quality. Анализ выполняется для всех медиафайлов, подходящих для анализа Quality. Соответствующую настройку можно отключить.

Documents

Сверка лица с документами (анализ “Documents”) выполняется для медиафайлов с тегами photo_id_front, photo_id_back (документы) и photo_selfie (селфи). Результат сверки будет положительным, если есть фото лица и хотя бы один валидный документ (с фотографией того же лица) из списка ниже:

• паспорт

• водительские права

• заграничный паспорт

Связанные с тегами ошибки

Ниже приведены разъяснения по каждому статусу.

Состояние анализа (analyse.state)

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

PROCESSING – в обработке;

FAILED – анализ выполнить не удалось, произошла ошибка;

FINISHED – выполнение анализа завершено.

Результат анализа (analyse.resolution_status)

Если выполнение анализа завершено, результат выполнения может принимать следующие значения:

SUCCESS– проверка пройдена успешно;

DECLINED – проверка не пройдена (лицо не совпало или совпало с лицом из ЧС в зависимости от настроек, атака, лицо не совпало с лицом в документах).

Если анализ не завершен, результат наследует значение из analyse.state: PROCESSING (еще в обработке) / FAILED (возникли ошибки, завершить анализ не удалось).

Состояние заявки (folder.resolution_status)

Заявка – это папка, в которой лежат медиафайлы для анализа. Если анализы еще не завершены, в resolution_status вы увидите одно из следующих значений:

INITIAL – анализы не назначены;

PROCESSING – анализы выполняются;

FAILED – выполнить анализы не удалось (произошли ошибки);

FINISHED – папка обработана, выполнение анализов завершено.

Результат заявки (system_resolution)

Результат заявки – консолидированный результат всех анализов, назначенных для медиафайлов из этой папки. Обратите внимание: результат заявки представляет собой результат группы анализов, завершившейся последней. Если все назначенные анализы выполнены, результат будет:

SUCCESS– все хорошо, проверки пройдены успешно;

OPERATOR_REQUIRED (кроме анализа Liveness) – анализы со статусом DECLINED отсутствуют, но один или больше анализов завершились со статусом OPERATOR_REQUIRED;

DECLINED – один или больше анализов завершились с результатом DECLINED, то есть проверка не прошла.

В Oz Api существует несколько видов анализов:

• ,

• ,

• ,

• .

Biometry

Назначение

Биометрический алгоритм позволяет сравнить несколько фото и оценить уровень схожести запечатленных на них людей. В качестве источников проверки можно передавать фото, видео и страницы документов с фото. Для корректной работы нужно как минимум 2 файла-источника (подробности смотрите на странице ).

Результат

Анализ выдает уровень схожести изображений лиц в процентах от 100 до 0% (1->0), где:

• 100% (1) – максимальная схожесть,

• 0% (0) – схожесть отсутствует.

Quality (Liveness, Best Shot)

Назначение

Алгоритм определения живости Liveness (анализ Quality) предназначен для проверки наличия живого человека в коротком видеоролике или на фото.

Результат

Анализ выдает возможность спуфинга*/атаки в процентах, где:

• 100% (1) – атака, перед камерой не живой человек,

• 0% (0) – перед камерой реальный человек в сознании.

*Спуфинг в биометрической области – (англ. spoofing – подмена) это ситуация, в которой человек маскируется под другого человека, используя программные и не программные средства (виртуальная камера, демонстрация изображения лица с экрана смартфона или фотографии, маски или силиконовой головы).

Documents

Назначение

Анализ распознавания и проверки документов предназначен для базового определения наличия документа в кадре и проверки корректности полей документа согласно его типу. Параллельно проводится биометрический анализ (сверка фотографии из документа и селфи, сделанного человеком).

Результат

Анализ документов выдает два варианта результатов:

• Документы успешно проверены,

• Документы не прошли проверку.

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

Blacklist

Назначение

Алгоритм проверки по черному списку предназначен для проверки присутствия человека в базе заранее загруженных фото.

База заранее загруженных фото может называться как "Черным списком", если туда внесены фотографии лиц мошенников или других нежелательных для бизнеса людей, так и "Белым списком", если она содержит фотографии лиц VIP-персон.

Результат

Анализ по черному списку выдает процент схожести от 100 до 0% (1->0), где:

• 100% (1) – это максимальная схожесть, алгоритм нашел совпадения с изображениями из черного списка.

• 0% (0) – минимальная схожесть, алгоритм не нашел совпадений с изображениями из черного списка.

Роли указываются при создании новых пользователей и созданы для ограничения доступа к API при интеграции с прямым доступом.

Каждая роль комбинируется с флагами is_admin и is_service и в зависимости от них может менять поведение.

Флаг is_service предназначен для создания сервисных пользователей учётных записей для входа автоматизированным способом. При авторизации под таким пользователем выдаётся токен с долгим временем жизни (по умолчанию 5 лет). Время жизни токенов для обычных пользователей составляет 15 минут (параметризуется), по умолчанию время жизни токенов продлевается при каждом обращении (параметризуется).

• ADMIN – Администратор системы. Имеет неограниченный доступ ко всем ресурсам системы через API, кроме принятия решений по анализам;

• OPERATOR – Системный оператор. Имеет неограниченный доступ на просмотр заявок и может принимать решения по анализам, с помощью кнопки Принять решение (обычно используется в случае появления OPERATOR_REQUIRED);

• CLIENT – Клиентская учетная запись. В рамках своей компании имеет доступ к загрузке медиафайлов, запуску анализов, просмотру результатов в своих папках, выгрузке отчетности по заявке;

  • is_admin – если установлен, пользователь получает доступ к данным всех пользователей внутри своей компании

  • can_start_analyse_biometry – дополнительный флаг для ограничения доступа к проведению биометрии (по умолчанию разрешено)

  • can_start_analyse_quality – дополнительный флаг для ограничения доступа к проведению анализов Liveness (по умолчанию разрешено)

• CLIENT ADMIN – администратор компании, который может управлять пользователями и аккаунтом своей компании. CLIENT ADMIN может просматривать данные всех пользователей и редактировать их, просматривать статистику, удалять файлы в папках, шаблоны отчетов вместе с вложениями, сами отчеты и отдельные анализы, а также может добавлять шаблоны отчетов и изображения в ЧС. Роль есть только в Web UI, вне Web UI она заменяется на роль CLIENT c флагом is_admin = true.

• CLIENT OPERATOR – имеет такие же права, как и OPERATOR, но в рамках своей компании.

Подробное описание уровней доступа приведено ниже.

Компания

Папка

Шаблон отчета

Приложения к шаблону отчета

Отчет

Анализ

Коллекция

Персона

Фото персоны

Пользователь

Иерархия объектов

Объекты системы имеют иерархическую структуру подчинения.

1. На верхнем уровне находится Компания. Это значит, что один экземпляр установки Oz API может обслуживать пользователей нескольких не зависящих друг от друга компаний.

Поля объектов

Каждый объект имеет набор полей для работы и идентификации на уровне REST API запросов.

Общие поля

Объект Компания

Объект Пользователь

Объект Папка

Объект Медиа

Объект Анализ

Oz API Lite – это версия Oz API, менее требовательная к ресурсам, более простая и производительная. Повышение производительности достигается благодаря отсутствию дополнительных функций (таких, как хранение данных или сбор статистики), а также тому, что анализы запускаются на уровне образа API Lite.

Отличия архитектуры Lite от типовой

• Только один компонент, который нужно кластеризовать.

• Нет хранилища данных – более высокий уровень защиты информации.

• Более простая архитектура – более короткие сроки реализации проекта.

Примеры методов

Для проверки корректности работы процессора Liveness используйте GET /v1/face/liveness/health.

Для проверки корректности работы процессора Biometry используйте GET /v1/face/pattern/health.

Чтобы выполнить liveness-проверку лица на изображении, вызовите POST /v1/face/liveness/detect (на вход принимает изображение, на выходе выводит оценку присутствия презентационной атаки на этом изображении).

Для сравнения лиц на двух изображениях вызовите POST /v1/face/pattern/extract_and_compare (принимает два изображения, извлекает из них биометрические шаблоны и сравнивает эти шаблоны). Также возможно сравнение одного изображения с несколькими с помощью POST /v1/face/pattern/extract_and_compare_n.

Полный список методов Oz API Lite с детальной информацией по ним вы можете найти .

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

Коды HTTP-ответов

• Коды ответов в диапазоне 2XX соответствуют корректно отработавшему запросу (например, при получении данных возвращается код 200, при добавлении новой сущности – 201, при корректном удалении – 204 и так далее);

• Коды ответов в диапазоне 4XX соответствуют ошибке при обработке запроса, произошедшей на стороне вызывающего клиента (например, 404 – обращение к несуществующему ресурсу);

• Коды ответов в диапазоне 5XX соответствуют ошибке при обработке запроса на стороне самой системы (например, при временной недоступности базы данных).

Тело ответа при ошибке

Каждая ошибка, возникшая при обработке запроса на стороне системы, помимо соответствующего HTTP-кода ошибки содержит также описание самой ошибки в теле ответа с указанием следующих JSON-полей:

• error_code – целочисленный код ошибки;

• error_message– сообщение с описанием возникшей ошибки (используется только для отладочных задач и расследования инцидентов);

• details – детали ошибки (приводятся в произвольном формате, специфичном для каждого отдельного типа ошибки). Необязательное поле.

Пример ответа сервера:

Коды ошибок:

Для работы с Oz API вы можете использовать свободно распространяемое ПО Postman. Скачайте клиентскую часть Postman по и установите ПО.

Загрузите JSON-файл с нужной коллекцией Postman:

Коллекция Oz API

5.2

5.0

Oz API 5.1.0 работает с этой же коллекцией.

4.0

3.33

Импорт коллекции Postman

После запуска клиента необходимо импортировать актуальную коллекцию для Postman, для этого в клиенте нажмите кнопку Import:

Нажмите files для выбора файла, найдите нужный JSON и нажмите Открыть:

Импортированная коллекция со всеми методами взаимодействия появится в интерфейсе Postman:

5.2.0 – 06.09.2024

• Обновили коллекцию Postman. Опубликовали новую коллекцию здесь и на https://apidoc.ozforensics.com/.

• Добавили метод проверки настроек таймзоны: GET {{host}}/api/config

• Добавили параметры к методу GET {{host}}/api/event_sessions:

  • time_created

  • time_created.min

  • time_created.max

  • time_updated

  • time_updated.min

  • time_updated.max

  • session_id

  • session_id.exclude

  • sorting

  • offset

  • limit

  • total_omit

• При создании папки с SHOT_SET соответствующее видео будет в media.video_url.

• Исправили ошибку, из-за которой CLIENT ADMIN не мог установить новый пароль для пользователя из своей компании.

5.1.1 – 16.07.2024

• Обновления безопасности.

5.1.0 – 20.03.2024

• Добавили возможность сравнения лица с большой базой фотографий, содержащей миллион фото и более, – Face Identification 1:N.

• Анализ Liveness (QUALITY) теперь игнорирует фото с тегами photo_id, photo_id_front или photo_id_back.

5.0.1 – 16.07.2024

• Обновления безопасности.

5.0.0 – 17.11.2023

• Анализ Liveness (QUALITY) теперь работает и с изображениями.

• Исправили ошибку, из-за которой анализ Liveness мог завершиться с успехом при отсутствии медиафайлов в папке (заявке).

• Для extract_best_shot изменили значение по умолчанию на True.

• Архивы RAR больше не поддерживаются.

• По умолчанию в analyses.results_media.results_data теперь один параметр: confidence_spoofing. Если для обратной совместимости нужны все три (confidence_replay, confidence_liveness и confidence_spoofing), это можно настроить.

• Обновили PDF-отчет, который грузится по умолчанию.

• Название PDF-отчета теперь содержит folder_id.

4.0.8-patch1 – 16.07.2024

• Обновления безопасности.

4.0.8 – 22.05.2023

• Настроили авторотацию логов.

• Добавили консольную команду для удаления пользователя.

• Генерацию предпросмотра видео теперь можно отключить.

• Токен доступа для роли ADMIN теперь действителен 5 лет.

• Добавили идентификатор папки folder_id к названию отчета.

• Исправили ошибки и оптимизировали работу API.

4.0.2 – 13.09.2022

• Система теперь удаляет ненужные кадры, оставшиеся после раскадровки видео.

• Добавили новые методы GET and POST для media/<media_id>/snapshot/

• Заменили шаблон отчета по умолчанию.

• Превью для набора кадров теперь показывается с исходным соотношением сторон.

• ADMIN и OPERATOR автоматически добавляются в system_company.

• Для User, Folder, Analyse, Media добавили атрибут company_id.

• Для Analysis добавили атрибут group_id.

• Для Folder и Analysis добавили атрибут system_resolution.

• resolution_status теперь возвращает значение system_resolution.

• Убрали метод PATCH для коллекций.

• Добавили фильтр по resolution_status для Folder Analyses [LIST] и по analyse.resolution_status для Folder [LIST].

• Для Folder, User, Company добавили журналирование.

• Обновили алгоритм удаления компании.

• Улучшили логику обработки черных списков.

• Исправили несколько багов.

3.33.0

• Модули Photo Expert и KYC удалены.

• Обновили конечную точку для изменения пароля пользователя: POST users/user_id/change-password вместо PATCH.

3.32.1

• Доступен лог для Celery.

3.32.0

• Добавили в параметры запроса Folder [LIST] фильтры: analyse.time_created, analyse.results_data для анализа Documents, results_data для анализа Biometry, results_media_results_data для анализа QUALITY. Для включения фильтра установите True в параметре запроса with_results_media_filter.

3.31.0

• Добавили новый атрибут для пользователей – is_active (по умолчанию True). Если выставлено False, пользователь не может совершать никакие действия.

• Добавили новую ошибку, которая выводится в ответ на попытку заблокированного пользователя что-либо сделать.

3.30.0

• Добавили превью наборов изображений.

• Теперь наборы можно сохранять на диск через атрибуты original_local_path, original_url.

• Добавили атрибут original_info для набора изображений – в нем хранятся сумма md5, размер, mime-тип.

• Исправили отчет для наборов изображений.

3.29.0

• Добавили “проверку здоровья” системы - метод GET api/healthcheck. Можно задать перечень имен / очередей задач на проверку активности.

3.28.1

• Поправили ссылку на миниатюру для набора изображений.

3.28.0

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

3.27.0

• Поменяли политики – максимальное количество попыток анализа увеличили до 3 и ввели настраиваемую задержку.

• Поменяли алгоритм вызова callbacks.

• Переработали и описали инструменты командной строки.

• Провели рефакторинг модулей.

3.25.0

• Поменяли подметод и метод для удаления персональных данных – с delete_pi на /pi и с POST на DELETE соответственно.

3.23.1

• Улучшили алгоритм удаления персональных данных.

• В папки, которые были очищены, теперь нельзя добавлять медиа.

3.23.0

• Поменяли название подметода авторизации с auth на auth_restore.

• Добавили тег video_selfie_oneshot.

• Добавили настройки валидации пароля.

• Добавили задержки для auth, rest_unauthorized, rps_with_token (OZ_THROTTLING_RATES в настройках, по умолчанию отключено).

• Теперь можно проверять доступы пользователя к статичным файлам (OZ_USE_PERMISSIONS_FOR_STATIC в настройках, по умолчанию – False).

• Добавили новый подметод для заявки - /delete_pi. С его помощью можно удалить в заявке все персональные данные и связанные с ними анализы.

3.22.2

• Добавили ошибку, которая появляется при попытке синхронизировать пустые коллекции.

3.22.0

• Добавили параметр fields_to_check к анализу документов (по умолчанию проверяет все поля).

• Добавили параметр double_page_spread к анализу документов (по умолчанию включен).

3.21.3

• Поправили синхронизацию коллекций.

3.21.0

• Теперь можно продлить токен авторизации с помощью expire_token.

3.20.1

• Добавили поддержку application/x-gzip.

3.20.0

• Переименовали shots_set.images в shots_set.frames.

3.18.0

• Добавили набор функций по управлению сессиями пользователя.

• Пользователи могут менять владельцев заявок (в соответствии со своими доступами).

• Поменяли правила зависимостей.

• Поправили баг с продлением авторизации.

3.16.0

• Переместили функционал синхронизации коллекций в oz_core.

3.15.3

• Упростили работу с наборами изображений. Один набор – один архив.

3.15.2

• Улучшено распознавание документов для Dockered-версии.

3.15.1

• Переместили проверку тега ориентации в анализ Quality.

3.15.0

• Добавили шаблон отчета по умолчанию для ролей Admin и Operator.

3.14.0

• Обновили биометрическую модель.

3.13.2

• Исправили ошибку с созданием объекта набора изображений без изображений.

• Добавили новый формат обмена данными для модуля распознавания документов.

3.13.1

• Если для персон в коллекции проводились какие-либо анализы, коллекцию теперь нельзя удалить.

3.13.0

• Добавили к анализам временные метки time_task_send_to_broker, time_task_received, time_task_finished.

3.12.0

• Добавили новый механизм авторизации – соединение с Active Directory через LDAP.

3.11.0

• Добавили новый тип медиа в заявку: "shots_set"

• Персону в коллекции теперь нельзя удалить, если с ней производились какие-либо анализы.

3.10.

• Переименовали поле заявки resolution_suggest в operator_status.

• Добавили к заявке текстовое поле operator_comment.

• Доступ на редактирование полей заявки operator_status и operator_comment есть у Admin, Operator, Client Service, Client Operator и Client Admin.

• Доступ на удаление заявки, медиа из заявки, шаблонов отчетов и их вложений, самих отчетов и анализов теперь есть только у Admin и Client Admin (в рамках компании).

3.9.0:

• Исправили удаление отчетов – теперь они удаляются при удалении их автора.

3.8.1

• Поправили доступы – Client теперь может просматривать только свой профиль.

3.8.0

• Client Operator теперь может редактировать только свой профиль.

• Client больше не может удалять свои заявки, любые медиа, отчеты или анализы.

• Client Service может создавать персон в коллекциях и просматривать отчеты в рамках компании.

3.7.1

• У ролей Client, Client Admin, Client Operator теперь есть доступы на просмотр профилей пользователя только внутри компании.

• Запустили альфа/бета-тестирование.

• Теперь поддерживаем заголовок с датой просрочки токена авторизации.

• Добавили поддержку модуля распознавания документов для стенделона и Docker.

3.7.0

• Добавили роль Client Operator – это Client Admin, но без доступа к управлению аккаунтом и компанией.

• И Client Admin, и Client Operator могут менять статус анализа.

• Создавать, редактировать и удалять что-либо в моделях Collection и CollectionPerson в рамках компании теперь могут только Admin и Client Admin.

• При создании отчета по заявке теперь проверяются доступы пользователя к шаблонам.

• Поправили код статуса, который возвращается при создании коллекции, с 200 на 201.

1.2.2 – 17.10.2024

• Обновили модели.

1.2.1 – 05.09.2024

• С помощью метода Liveness detect теперь можно отправить не более 10 файлов в одном запросе, при этом размер каждого файла не должен превышать 15 МБайт.

• Обновили список жестов, которые поддерживают отправку лучшего кадра (best_shot): включили повороты, наклон и подъем головы, а также улыбку и моргание.

1.2.0 – 26.07.2024

• Обновили метод Liveness detect: теперь он работает также и с видео и архивами.

1.1.1 – 28.11.2022

• Добавили метод для проверки версий компонентов

1.1.0

• API Lite теперь работает и с base64

09.2021

• Улучшили биометрическую модель

• Добавили режим 1:N

08.2021

• Добавили политику CORS

• Подготовили первую версию документации

06.2021

• Переработали сообщения об ошибках, теперь они более информативны

• Упростили операции Liveness/Detect

04.2021

• Переработали ядро

• Добавили операции для защиты от спуфинга

10.2020

• Добавили операцию extract_and_compare

Для работы с Oz API Lite вы можете использовать свободно распространяемое ПО Postman. Скачайте клиентскую часть Postman по ссылке и установите ПО.

Загрузите JSON-файл с коллекцией Postman:

1.2.0

1.1.1

Импорт коллекции Postman

После запуска клиента необходимо импортировать актуальную коллекцию для Postman, для этого в клиенте нажмите кнопку Import:

Нажмите files для выбора файла, найдите нужный JSON и нажмите Открыть:

Импортированная коллекция со всеми методами взаимодействия появится в интерфейсе Postman:

version – проверка версии компонентов

С помощью этого метода можно узнать, какие версии компонентов используются (начиная с версии 1.1.1).

Call GET /version

Входные параметры

-

Пример запроса

GET localhost/version

Успешный ответ метода

В случае успешного ответа метод возвращает сообщение со следующими параметрами.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Пример ответа

200 OK
Content-Type: application/json
{
2	"core": "core_version",
3	"tfss": "tfss_version",
4	"models": [
5		{
6			"name": "model_name",
7			"version": "model_version"
8		}
9	]
10}

Биометрия

health – проверка состояния биометрического процессора biometry

С помощью этого метода можно проверить, корректно ли работает процессор.

Вызов метода: GET /v1/face/pattern/health

Входные параметры

-

Пример запроса

GET localhost/v1/face/pattern/health

Успешный ответ метода

В случае успешного ответа метод возвращает сообщение со следующими параметрами.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Пример ответа

200 OK
Content-Type: application/json
{“status”: 0, message: “”}

extract – извлечение биометрического шаблона

Метод предназначен для извлечения биометрического шаблона из изображения. Тип контента HTTP-запроса: “image/jpeg” или “image/png”

Вызов метода: POST /v1/face/pattern/extract

Входные параметры

Пример запроса

POST localhost/v1/face/pattern/extract
Content-Type: image/jpeg
{Поток байт изображения}

Успешный ответ метода

В случае успешного ответа метод возвращает биометрический шаблон.

Тип контента HTTP-ответа: “application/octet-stream”.

Выходные параметры

Пример ответа

200 OK
Content-Type: application/octet-stream
{Поток байт биометрического шаблона}

compare – сравнение биометрических шаблонов

Метод предназначен для сравнения двух биометрических шаблонов.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/compare

Входные параметры

Пример запроса

POST localhost/v1/face/pattern/compare
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”bio_feature”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”bio_template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результат сравнения двух шаблонов.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Пример ответа

200 OK
Content-Type: application/json
{“score”: 1.0, “decision”: “approved”}

verify – биометрическая верификация

Метод объединяет два описанных выше метода extract и compare – извлекает биометрический шаблон из изображения и сравнивает его с другим биометрическим шаблоном, который также передается в запросе.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/verify

Входные параметры

Пример запроса

POST localhost/v1/face/pattern/verify
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”bio_template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”sample”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результат сравнения двух биометрических шаблонов.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Пример ответа

200 OK
Content-Type: application/json
{“score”: 1.0, “decision”: “approved”}

extract_and_compare – извлечение из двух изображений и сравнение полученных шаблонов

Метод объединяет два описанных выше метода extract и compare. Он извлекает биометрические шаблоны из двух изображений, сравнивает их и в качестве ответа передает результат сравнения.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/extract_and_compare

Входные параметры

Пример запроса

POST localhost/v1/face/pattern/extract_and_compare
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”sample_1”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”sample_2”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результат сравнения двух извлеченных биометрических шаблонов.

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Пример ответа

200 OK
Content-Type: application/json
{“score”: 1.0, “decision”: “approved”}

compare_n – сравнение биометрических шаблонов 1:N

Метод предназначен для сравнения биометрических шаблонов в режиме 1:N.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/compare_n

Входные параметры

Пример запроса

POST localhost/v1/face/pattern/compare_n
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”template_1”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”1.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”2.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”3.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результаты сравнений 1:N .

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Пример ответа

200 OK
Content-Type: application/json
{'results': [
    {'filename': '1.template', 'score': 0.0, 'decision': 'declined'}, 
    {'filename': '2.template', 'score': 1.0, 'decision': 'approved'}, 
    {'filename': '3.template', 'score': 0.21, 'decision': 'declined'}
]}

verify_n – биометрическая верификация 1:N

Метод объединяет два описанных выше метода extract и compare_n. Метод извлекает биометрический шаблон из изображения и сравнивает его cо списком биометрических шаблонов, которые также передаются в запросе.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/verify_n

Входные параметры

Пример запроса

POST localhost/v1/face/pattern/verify_n
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”sample_1”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”1.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”2.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”3.template”
Content_type: application/octet-stream
{Поток байт биометрического шаблона}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результаты сравнений 1:N .

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Пример ответа

200 OK
Content-Type: application/json
{'results': [
    {'filename': '1.template', 'score': 0.0, 'decision': 'declined'}, 
    {'filename': '2.template', 'score': 1.0, 'decision': 'approved'}, 
    {'filename': '3.template', 'score': 0.21, 'decision': 'declined'}
]}

extract_and_compare_n – извлечение и сравнение полученных шаблонов 1:N

Метод объединяет два описанных выше метода extract и compare_n. Он извлекает биометрические шаблоны из изображения-кандидата и изображений из списка, а затем сравнивает их в режиме 1:N.

Тип контента HTTP-запроса: “multipart/form-data”.

Вызов метода: POST /v1/face/pattern/extract_and_compare_n

Входные параметры

Пример запроса

POST localhost/v1/face/pattern/extract_and_compare_n
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Длина тела сообщения
--BOUNDARY--
Content-Disposition: form-data; name=”sample_1”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”samples_n”; filename=”1.jpeg”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”samples_n”; filename=”2.jpeg”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--
Content-Disposition: form-data; name=”samples_n”; filename=”3.jpeg”
Content_type: image/jpeg
{Поток байт изображения}
--BOUNDARY--

Успешный ответ метода

В случае успешного ответа метод возвращает результаты сравнений 1:N .

Тип контента HTTP-ответа: “application/json”.

Выходные параметры

Пример ответа

200 OK
Content-Type: application/json
{'results': [
    {'filename': '1.jpeg', 'score': 0.0, 'decision': 'declined'}, 
    {'filename': '2.jpeg', 'score': 1.0, 'decision': 'approved'}, 
    {'filename': '3.jpeg', 'score': 0.21, 'decision': 'declined'}
]}

Ошибки методов

Тип контента HTTP-ответа: “application/json”.

Liveness

health – проверка состояния биометрического процессора liveness

Вызов метода: GET /v1/face/liveness/health

Входные параметры отсутствуют.

Пример запроса

GET localhost/v1/face/liveness/health

Успешный ответ метода

В случае успешного ответа метод возвращает сообщение со следующими параметрами.