В этом разделе описано, как выполнять проверки в рамках основных сценариев использования.
Liveness – проверка «живости», того, что человек, снятый на видео, действительно живой реальный человек в сознании.
Биометрия – сравнение двух или более лиц с различных фотографий или видеороликов с целью ценить степень их схожести (один и тот же это человек или разные люди).
Лучший кадр – выбор лучшего кадра из видеоролика для использования его в бизнес-процессах как результата Liveness-проверки, «видео в виде картинки».
Проверка по ЧС (черному списку) – проверка, присутствует ли человек, чье фото или видео загружается в систему, в базе заранее загруженных фотографий.
В source_media указывается media_id из ответа предыдущего запроса. Это опционально, если требуется проверить одно из двух заранее загруженных в папку видео.
Сохраните analyse_id из ответа.
4а. Через некоторое время .
Дождитесь, когда поля resolution_status и resolution изменят статус на любой, кроме PROCESSING, – этот статус и будет результатом.
4б. Еще один вариант: добавьте , который обратится к вашему сайту по завершении анализа. В payload запроса добавьте нужный адрес в поле resolution_endpoint:
В запросе вебхука будет содержаться информация о папке и связанных с ней анализах.
Алгоритм проверки Collection предназначен для проверки присутствия человека по базе заранее загруженных фотографий. В качестве источника для сравнения можно использовать изображение и/или фрагмент видео.
В source_media указывается media_id из ответа предыдущего запроса. Это опционально, если требуется проверить одно из двух заранее загруженных в папку видео.
Сохраните analysis_id из ответа.
4а. Через некоторое время п. Дождитесь, когда поля resolution_status и resolution изменят статус на любой, кроме PROCESSING, – этот статус и будет результатом.
4б. Еще один вариант: добавьте , который обратится к вашему сайту по завершении анализа. В payload запроса добавьте нужный адрес в поле resolution_endpoint:
В запросе вебхука будет содержаться информация о папке и связанных с ней анализах.
Подробно статусы анализов описаны .
Если вы хотите узнать, с кем именно из вашей базы фотографий совпало лицо с медиафайла, который вы только что загрузили, найдите в ответе анализ collection, в нем results_media, где и будет идентификатор нужной вам персоны person_id. Чтобы получить информацию об этой персоне, вызовите метод GET /api/collections/{{collection_id}}/persons/{{person_id}}, указав идентификаторы вашей коллекции и персоны в ней.
Результаты анализов
Здесь вы узнаете, как через API получить результаты выполненных анализов.
Результат любого анализа представляет собой число. Для анализа Biometry это число отражает степень совпадения/несовпадения лиц в загруженных вами медиафайлах по сравнению с референсами – теми файлами, которые хранятся в базе. Для анализа Liveness – возможность того, что на загруженном медиафайле не реальный живой человек в сознании, а какое-то его изображение или deepfake. Результаты анализов можно узнать и без захода в каждую заявку по отдельности – API предоставляет возможность извлечь их из JSON-ответа.
Сделайте запрос к заявке или . Параметр with_analyses должен быть установленTrue.
Для типа анализа Biometry ищите значение параметра min_confidence:
Этот параметр отражает уверенность системы в том, что на представленных медиа фигурирует один и тот же человек.
4. Для типа анализа Liveness Analysis ищите значение параметра confidence_spoofing для нужного медиафайла:
Этот параметр показывает вероятность спуфинг-атаки – того, что на полученном видео, например, использовалась технология deepfake или вместо человека программе показали видеоролик с этим человеком.
Если нужно обработать несколько результатов анализов, запросите список заявок и сделайте парсинг JSON-ответа.
Поиск лучшего кадра
Алгоритм "лучший кадр" выбирает из видеозаписи наиболее качественный и удачный кадр с лицом. Алгоритм вызывается дополнительно к анализу .
Внимание: в некоторых случаях конфигурация позволяет использовать "лучший кадр" только для определенных жестов.
3. Запустите анализ. Убедитесь, что параметр "extract_best_shot" имеет значение True, как показано ниже.
В source_media указывается media_id из ответа предыдущего запроса. Это опционально, если требуется проверить одно из двух заранее загруженных в папку видео.
Сохраните analyse_id из ответа.
4а. Через некоторое время проверьте результат. Дождитесь, когда поля resolution_status и resolution изменят статус на любой, кроме PROCESSING, – этот статус и будет результатом.
4б. Еще один вариант: добавьте вебхук, который обратится к вашему сайту по завершении анализа. В payload запроса добавьте нужный адрес в поле resolution_endpoint:
В запросе вебхука будет содержаться информация о папке и связанных с ней анализах.
{
"resolution_endpoint": "address.com",
{
.... // информация о папке и т.д.
}
}
Аутентификация
Как получить и обновить токены доступа.
Аутентификация пользователя
Чтобы получить токены доступа, нужно выполнить POST-запрос на /authorize/auth/. В теле запроса нужно указать полученные от нас электронную почту и пароль в составе credentials, а также API-адрес в качестве адреса хоста.
Body
Результатом аутентификации пользователя является пара access_token и expire_token.
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 в заголовках.
Положительным результатом будет ответ с новой парой access_token и expire_token.
Предыдущая пара access_token и expire_token будет удалена из базы данных при первой аутентификации по новой паре access_token и expire_token.
Возможные ошибки
Теги медиафайлов
Каждый загружаемый медиафайл требуется маркировать специальными тегами. Это необходимо для корректной работы алгоритмов распознавания. Теги для видео и фото отличаются друг от друга.
Теги видеофайлов
Для видеофайлов в Системе должны быть указаны следующие типы тегов:
Тег, определяющий тип данных «видео»:
video_selfie
Тег, определяющий ориентацию видео:
orientation_portrait – портретная ориентация;
orientation_landscape – ландшафтная ориентация.
Тег, определяющий действие на видео:
video_selfie_left – поворот головы налево;
video_selfie_right – поворот головы направо;
Алгоритмы распознают файлы с тегами из этого списка как подходящие для выполнения анализов (Liveness) и .
Важно: в версии API 4.0.8 или старше, чтобы отправить на анализ Quality (Liveness) изображение, а не видео, необходимо поместить его в архив .zip, установить тип файла SHOTS_SET и поставить один из тегов video_, иначе Quality изображение проигнорирует.
Пример корректного набора тегов видеофайла с действием «моргание»:
Теги фотофайлов
Для фотофайлов в Системе должны быть указаны следующие типы тегов:
Тег для селфи:
photo_selfie – тег, определяющий тип фотографии «селфи»
Теги для фотографий или сканов удостоверений личности:
Важно: в версии API 4.0.8 или старше, чтобы отправить на анализ Quality (Liveness) изображение, а не видео, необходимо поместить его в архив .zip, установить тип файла SHOTS_SET и поставить один из тегов video_, иначе Quality изображение проигнорирует.
Пример корректного набора тегов фотофайла «селфи»:
Пример корректного набора тегов фотофайла с лицевой стороной документа:
Пример корректного набора тегов фотофайла с обратной стороной документа:
Работа с контейнером данных OzCapsula
Конфигурация Oz API
Основное изменение в работе с API – это новый content type для передачи данных. Контейнер представляет собой бинарный файл, поэтому установите Content-Type = application/octet-stream. Поддержка этого типа добавлена вместе с функциональностью контейнера.
Примеры
POST api/folders:
POST api/instant/folders:
Для Instant API также потребуются публичный и приватный ключи. Пути к этим ключам должны быть указаны в переменных OZ_JWT_PRIVATE_KEY_PATH и OZ_JWT_PUBLIC_KEY_PATH в файле конфигурации.
Генерация ключей:
Возможные ошибки
Получение Session Token
До начала работы с SDK получите session token:
(Опционально, только для stateful API) авторизуйтесь с любой ролью, кроме OPERATOR.
Вызовите метод GET {{host}}/api/authorize/session_token.
Пример запроса
Пример ответа
Биометрия
Биометрический алгоритм позволяет сравнить несколько фотографий и оценить уровень схожести людей на них. В качестве источников проверки можно передавать фото, видео и документы (с фото).
Дождитесь, когда поля resolution_status и resolution изменят статус на любой, кроме PROCESSING, – этот статус и будет результатом.
4б. Еще один вариант: добавьте , который обратится к вашему сайту по завершении анализа. В payload запроса добавьте нужный адрес в поле resolution_endpoint:
В запросе вебхука будет содержаться информация о папке и связанных с ней анализах.
Подробно статусы анализов описаны .
Instant API: режим работы без сохранения данных
В версии 6.0.1 мы добавили новый режим работы API – Instant. В этом режиме мы не сохраняем никакие данные, все, что вы отправляете и получаете, существует только в рамках вашего запроса и ответа на него. Таким образом вы экономите место в хранилище и, что может быть особенно важно в рамках соблюдения требований законодательства, не передаете и не храните чувствительные данные.
Чтобы включить режим Instant API, при подготовке файла конфигурации (config.py) для API установите параметру OZ_APP_COMPONENTS значение stateless. Чтобы никакие данные запроса и ответа не сохранялись, отправьте следующий запрос: POST /api/instant/folders/ . Авторизация настраивается на вашей стороне.
Обратите внимание: поскольку Instant API не хранит данные, работа в таком режиме с черным списком (1:N) не предусмотрена.
При использовании Instant API с Web SDK при установите параметру architecture значение lite. Версия Web SDK должна быть не ниже 1.7.14.
Минимальные системные требования
CPU: 16 ядер, 32 потока, базовая частота – 2.3 GHz, максимальная частота в турборежиме для одного ядра – 4 GHz.
RAM: 32 GB, DDR 5, Dual Channel.
Для расчета RPS и RPM и подбора оптимальной конфигурации под ваши задачи обратитесь к нам.
Параметры конфигурации
Перед запуском подготовьте файл конфигурации со следующими параметрами.
Обязательные параметры
Без этих параметров Instant API не запустится.
Установка
Docker
Docker Compose
Методы Instant API
Список методов доступен по . Также вы можете скачать коллекцию для Postman:
Типы анализов и что они проверяют
Виды и назначение биометрических анализов медиаданных в Oz Api, как интерпретировать результат.
В Oz Api существует несколько видов анализов:
,
,
Работа с коллекцией в Oz API
В этой статье рассказывается, как создать коллекцию методами API, как добавить в нее персону и фотографии, как потом все это удалить, а также удалить саму коллекцию. Все это можно также сделать , однако здесь мы описываем только соответствующие методы API.
Коллекция в Oz API – это база фотографий лиц (персон), которые используются в анализе Collection для сравнения с лицом человека с только что снятого фото или видео.
Персона – это сущность в коллекции, соответствующая одному человеку. Для одной персоны может быть загружено несколько фотографий.
Загрузка медиафайлов
Чтобы провести анализы для ваших медиафайлов, необходимо поместить их в папку – либо существующую, либо новую, созданную с помощью Oz API. Для каждого файла необходимо указать : они описывают, что это за файл и какие анализы к нему применимы.
Если у вас версия API 4.0.8 или старше, обратите внимание: если вы хотите загрузить фото с тем, чтобы позднее отправить его на анализ Liveness, поместите это фото в ZIP-архив и укажите для него теги, .
Создание папки и добавление в нее медиафайлов: /api/folders/
Коллекции Postman Oz API
Для работы с Oz API вы можете использовать свободно распространяемое ПО Postman. Скачайте клиентскую часть Postman по и установите ПО.
Загрузите JSON-файл с нужной коллекцией Postman.
6.0
Отдельная коллекция для Instant API:
Код ошибки
Сообщение об ошибке
Причина
400
Could not locate field for key_path expire_token from provided dict data
expire_token отсутствует в теле запроса.
401
Session not found
Не существует сессии с переданным expire_token.
403
You have not access to refresh this session
Пользователь, который делает запрос, не является владельцем сессии переданного expire_token.
Коллекция создается в рамках определенной компании, таким образом, для добавления новой коллекции необходим идентификатор компании 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}}/.
{
"analyses": [{
"type": "biometry",
// необязательный параметр
// если не указать, анализ будет назначен на все медиафайлы в папке
"source_media": [
"1111aaaa-11aa-11aa-11aa-111111aaaaaa",
"2222bbbb-22bb-22bb-22bb-222222bbbbbb"
]
}]
}
{
"resolution_endpoint": "address.com",
{
.... // информация о папке и т.д.
}
}
# список компонентов Oz API. Для Instant API укажите stateless
# для компонента авторизации добавьте auth
OZ_APP_COMPONENTS=stateless
# поддержка локального хранилища
OZ_LOCAL_STORAGE_SUPPORT_ENABLE=false
# адрес сервиса tfss
OZ_SERVICE_TFSS_HOST=http://xxx.xxx.xxx.xxx:xxxx
# разрешенные хосты
APP_ALLOWED_HOSTS=example-host1.com,example-host2.com
# секретный ключ
OZ_API_SECRET_KEY=long_secret_key
Возможные качественные результаты анализов описаны здесь: Статусы API.
У каждого из анализов есть пороговое значение, определяющее статус анализа на выходе. По умолчанию этот порог равен 0.5 или 50%, для Collection и Biometry (Face Matching) – 0.85 или 85%.
Biometry: значение не ниже порога означает, что лица совпадают.
Collection: значение не ниже порога означает, что лицо с проанализированного медиафайла совпало с одним из лиц в черном списке.
Quality: значение не ниже порога означает наличие атаки.
Чтобы настроить пороговое значение под ваши нужды, .
Больше информации по интерпретации численных результатов анализов вы можете найти здесь: .
Biometry
Назначение
Биометрический алгоритм позволяет сравнить несколько фото и оценить уровень схожести запечатленных на них людей. В качестве источников проверки можно передавать фото, видео и страницы документов с фото. Для корректной работы нужно как минимум 2 файла-источника (подробности смотрите на странице Правила назначения анализов).
Результат
Анализ выдает уровень схожести изображений лиц в процентах от 100 до 0% (1->0), где:
100% (1) – максимальная схожесть,
0% (0) – схожесть отсутствует.
Quality (Liveness, Best Shot)
Назначение
Алгоритм определения живости Liveness (анализ Quality) предназначен для проверки наличия живого человека в коротком видеоролике или на фото.
Алгоритм "лучший кадр" (best shot) выбирает из видеозаписи наиболее качественный и удачный кадр с лицом. Алгоритм вызывается дополнительно к анализу liveness.
Результат
Анализ выдает возможность спуфинга*/атаки в процентах, где:
100% (1) – атака, перед камерой не живой человек,
0% (0) – перед камерой реальный человек в сознании.
*Спуфинг в биометрической области – (англ. spoofing – подмена) это ситуация, в которой человек маскируется под другого человека, используя программные и не программные средства (виртуальная камера, демонстрация изображения лица с экрана смартфона или фотографии, маски или силиконовой головы).
Documents
Назначение
Анализ распознавания и проверки документов предназначен для базового определения наличия документа в кадре и проверки корректности полей документа согласно его типу. Параллельно проводится биометрический анализ (сверка фотографии из документа и селфи, сделанного человеком).
В Oz Api интегрирован сервис OCR-анализа документов от партнера. Также возможно использование другого сервиса OCR по желанию клиента. Свяжитесь сотделом продаж.
Результат
Анализ документов выдает два варианта результатов:
Документы успешно проверены,
Документы не прошли проверку.
Также выводится набор полей документа с результатами распознавания по каждому полю и результат биометрического анализа.
Collection
Назначение
Алгоритм проверки Collection предназначен для проверки присутствия человека в базе заранее загруженных фото.
База заранее загруженных фото может называться как "черным списком", если туда внесены фотографии лиц мошенников или других нежелательных для бизнеса людей, так и "Белым списком", если она содержит фотографии лиц VIP-персон.
Результат
Анализ по коллекции фото выдает процент схожести от 100 до 0% (1->0), где:
100% (1) – это максимальная схожесть, алгоритм нашел совпадения с изображениями из коллекции.
0% (0) – минимальная схожесть, алгоритм не нашел совпадений с изображениями из коллекции.
Анализы могут быть назначены медиафайлам как вручную пользователем – например, через выбор сценария 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 (селфи). Результат сверки будет положительным, если есть фото лица и хотя бы один валидный документ (с фотографией того же лица) из списка ниже:
паспорт
водительские права
заграничный паспорт
Связанные с тегами ошибки
Отправка на анализ единым запросом
В версии 6.0.1 мы добавили возможность отправить все необходимые для анализа данные и получить результат с помощью единственного запроса. До этого взаимодействие с API требовало последовательной отправки нескольких запросов: на , затем на назначение анализов (, , ), после этого – на получение результата (поллинг или ). Если вам нужны отдельные запросы, вы можете работать таким образом и дальше, но теперь есть и упрощенный способ: все это можно сделать одним запросом, включающим в себя все вышеуказанное.
Преимущества
Ошибки вызова сервиса
Полный список запросов вы можете найти в , в приведен порядок запросов в наиболее распространенных случаях. В данной статье перечислены коды ответов на запросы и ошибки при обработке запросов.
Коды HTTP-ответов
Коды ответов в диапазоне 2XX соответствуют корректно отработавшему запросу (например, при получении данных возвращается код 200, при добавлении новой сущности – 201, при корректном удалении – 204 и так далее);
Метаданные
Обзор
При создании какого-либо у вас может возникнуть необходимость хранить для него дополнительные данные, те, которые отсутствуют в базовом списке его параметров. Такие данные называются метаданными. Вы можете хранить любую нужную вам информацию в разделе meta_data в приведенном ниже формате ("название поля": "соответствующие полю данные"):
payload
{
"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"
]
}
}
Invalid/missed tag values to process blacklist check
Установленные для медиафайлов теги не могут быть обработаны алгоритмами Blacklist. Возможно, медиафайлам не установлены теги.
Код ошибки
Сообщение
Описание
202
Could not locate face on source media [media_id]
Лицо на медиа не найдено. Это может быть результатом неправильно выставленных (например photo_id_back) или отсутствующих тегов.
202
Biometry. Analyse requires at least 2 media objects to process
Алгоритмы не нашли хотя бы двух файлов для сравнения. Возможно, найден только один медиафайл или медиафайлам не установлены теги.
202
Processing error - did not found any document candidates on image
Документы на прилагаемых медиа не найдены – либо подгружено не фото документа, либо теги подгруженных медиафайлов отсутствуют / некорректны (не содержат photo_id в начале).
5
Invalid/missed tag values to process quality check
Установленные для медиафайлов теги относятся к тем, которые анализ Quality игнорирует (скорее всего, они начинаются с photo_, а не video_*).
Вся информация отправляется в одном запросе, снижая вероятность потери по пути части данных.
Синхронная работа – как только анализ завершится, вы получите результат, не нужно опрашивать сервер о готовности или настраивать вебхуки.
Высокая производительность – до 36 анализов в минуту на один сервер.
Использование
Чтобы отправить медиафайлы на анализ одним запросом, вызовите метод POST /api/folders/. В заголовке X-Forensic-Access-Token передайте ваш токен доступа. Добавьте в тело запроса нужные медиафайлы, а в payload – соответствующие им теги и, если нужно, метаданные.
Метаданные можно добавить к большинству объектов системы. Список объектов с соответствующими им методами для добавления метаданных приведен ниже. Также метаданные можно указать при создании объекта.
Метаданные можно также и менять, и удалять. Все нужные методы описаны в нашей документации по API.
Примеры использования
Метаданные могут вам потребоваться, например, если вы захотите группировать папки (заявки) по людям или лидам. Например, для подсчета конверсии в случаях, когда один лид делает несколько попыток пройти анализ Liveness, добавьте идентификатор этого лида в метаданные соответствующих папок.
Чтобы добавить идентификатор клиента iin к объекту папки, в тело запроса внесите соответствующую запись:
Вы можете передать в это поле идентификатор клиента и затем использовать его для получения запросов по одному и тому же клиенту или подсчета уникальных клиентов (одинаковый идентификатор = один и тот же клиент, разные идентификаторы = разные клиенты). Идентификатор может быть номером телефона, документа или любым другим уникальным идентификатором. Идентификатор будет отображаться в отчете отдельной колонкой.
Еще один частый случай использования метаданных связан с безопасностью: вы обрабатываете результат анализа на своем бэкенде, но не хотите при этом использовать идентификатор папки при обращении к ней. Добавьте отдельный идентификатор (transaction_id) в метаданные папки, и вы сможете искать нужную информацию по нему. Подробно этот случай использования описан здесь.
Если вы храните в метаданных персональные данные, убедитесь, что при этом не нарушаются соответствующие законы.
Метаданные можно также добавить через SDK, а затем работать с ними с помощью методов API. Добавление метаданных через SDK описано в соответствующих разделах:
Коды ответов в диапазоне 4XX соответствуют ошибке при обработке запроса, произошедшей на стороне вызывающего клиента (например, 404 – обращение к несуществующему ресурсу);
Коды ответов в диапазоне 5XX соответствуют ошибке при обработке запроса на стороне самой системы (например, при временной недоступности базы данных).
Тело ответа при ошибке
Каждая ошибка, возникшая при обработке запроса на стороне системы, помимо соответствующего HTTP-кода ошибки содержит также описание самой ошибки в теле ответа с указанием следующих JSON-полей:
error_code – целочисленный код ошибки;
error_message– сообщение с описанием возникшей ошибки (используется только для отладочных задач и расследования инцидентов);
details – детали ошибки (приводятся в произвольном формате, специфичном для каждого отдельного типа ошибки). Необязательное поле.
Пример ответа сервера:
Коды ошибок:
Код ошибки
Значение
Описание
0
UNKNOWN
Неизвестная серверная ошибка.
1
NOT ALLOWED
Вызван недопустимый метод, обычно сопровождается 405 статусом HTTP-ответа при вызове HTTP-метода, не поддерживаемого ресурсом (например PATCH, если ресурс поддерживает только GET/POST).
2
NOT REALIZED
Вызван web-сервис, который не реализован на сервере, может встретиться в случае, если сервис по документации присутствует, однако фактически не реализован (временно или на постоянной основе).
{
"error_code": 0,
"error_message": "Unknown server side error occurred",
"details": null
}
INVALID STRUCTURE
Некорректная структура запроса, обычно встречается, если не удается найти обязательный параметр или тело запроса передано в некорректном формате.
4
INVALID VALUE
Некорректное значение параметра, например может возникать в случаях: передана строка, которая должна иметь формат UUID, но при этом она не конвертируется корректно, передано отрицательное значение смещения/ширины окна при постраничном запросе.
Запрашиваемый ресурс не существует (аналог HTTP status_code = 404).
11
EXTERNAL SERVICE
Ошибка взаимодействия с внешней информационной системой.
12
DATABASE
Критическая ошибка работы с базой данных на стороне сервера.
начальное состояние
начальное состояние
анализы в процессе
анализы в процессе
FAILED
ошибка системы
ошибка системы
ошибка системы
ошибка системы
FINISHED
успешное завершение
-
успешное завершение
DECLINED
-
отрицательный анализ
-
отрицательный анализ
OPERATOR_REQUIRED
-
требуется перепроверка
-
требуется перепроверка
SUCCESS
-
положительный анализ
-
положительный анализ
Ниже приведены разъяснения по каждому статусу.
Состояние анализа (analyse.state)
Состояние выполнения анализа принимает следующие значения:
PROCESSING – в обработке;
FAILED – анализ выполнить не удалось, произошла ошибка;
FINISHED – выполнение анализа завершено.
Результат анализа (analyse.resolution_status)
Если выполнение анализа завершено, результат выполнения может принимать следующие значения:
SUCCESS– проверка пройдена успешно;
OPERATOR_REQUIRED (кроме анализа Liveness) – требуется оператор (т.е. дополнительная проверка человеком);
Наличие/отсутствие статуса OPERATOR_REQUIRED зависит от настроек биометрии.
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, то есть проверка не прошла.
Анализы, которые вы отправляете в одном POST-запросе, объединяются в группу. Результат группы анализов определяется по "худшему" из результатов анализов в этой группе: INITIAL > PROCESSING > FAILED > DECLINED > OPERATOR_REQUIRED > SUCCESS, где SUCCESS означает, что все проверки прошли успешно без каких-либо ошибок.
INITIAL
-
-
начальное состояние
начальное состояние
PROCESSING
Использование вебхуков для получения результатов
Вебхуки (webhook) упрощают процесс получения результатов анализов. После запуска анализов не нужно инициировать опрос с проверкой, завершены ли анализы. Вместо этого в запросе на анализы добавьте вебхук, который обратится к вашему веб-сайту, когда результаты будут готовы.
При создании папки добавьте нужный веб-адрес (resolution_endpoint) в раздел payload в теле запроса:
Postman
Пример payload
{
"resolution_endpoint": "address.com", // укажите нужный адрес здесь
... // остальные детали запроса
}
Каждый раз, когда анализы для этой папки будут готовы, вам будет приходить уведомление. Вебхук-запрос будет содержать результаты анализов и информацию о папке, для которой они выполнялись.
Объекты системы
Иерархия объектов
Объекты системы имеют иерархическую структуру подчинения.
На верхнем уровне находится Компания. Это значит, что один экземпляр установки Oz API может обслуживать пользователей нескольких не зависящих друг от друга компаний.
Пользователь является инициатором любого запроса. В зависимости от пользователя могут присутствовать определенные ограничения на те или иные действия.
При выполнении Пользователем запроса на Анализ система автоматически создает Папку, помещает туда все отправленные пользователем Медиафайлы, а затем запускает собственно (один или несколько). Анализы применяются к медиафайлам из папки в соответствии с . Требования к медиафайлам перечислены .
Поля объектов
Каждый объект имеет набор полей для работы и идентификации на уровне REST API запросов.
Общие поля
Объект Компания
Объект Пользователь
Объект Папка
Объект Медиа
Объект Анализ
технические поля, зарезервированные для работы модулей
фамилия
middle_name
String
отчество
email
String
email, который является логином пользователя
password
String
пароль, указывается при добавлении нового пользователя или при изменении пароля. Если пользователя не admin, необходимо указать поле password_old
can_start_analyze_*
String
см.
company_id
UUID
код компании пользователя
is_admin
Boolean
is_service
Boolean
список для этого файла
данные результата анализа
Поле
Тип
Описание
time_created
Timestamp
время создания объекта (кроме пользователя и компании)
Нарушение обратной совместимости: чтобы подключение при использовании S3 не пропадало, установите OZ_STATIC_S3_BUCKET_URL="None".
Контейнер теперь можно отправить в уже существующую папку. Используйте метод POST api/folders/{folder_id}/media.
Повысили производительность анализа Collection.
Слишком длинные видео теперь можно обрезать. Установите параметру OZ_FFMPEG_VIDEO_CROPPING_ENABLED значению true для автоматической обрезки всех видео длиннее OZ_VIDEO_DURATION_MAX. Записи об обрезке сохраняются в логах.
При невозможности обработки контейнера (ошибка 14) для упрощения расследования мы теперь сохраняем и данные соответствующей заявки.
Для невалидных контейнеров, чтобы удобнее было искать информацию, теперь сохраняем в логах API folder_id.
При удалении папки в конфгурациях local-local и local-s3 файлы статики теперь удаляются корректно.
6.4.1-40 – 24.12.2025
Добавили новую функциональность: проприетарный формат передачи данных OzCapsula.
Исправлена проблема с периодическими ложными отказами при использовании медиа, полученных из Web SDK.
Анализ Collection теперь игнорирует изображения с тегом photo_id_back.
6.4.0 – 24.11.2025
Только для SaaS.
Обновили API в рамках подготовки к внедрению новой функциональности.
6.3.5 – 03.11.2025
Исправили ошибки, из-за которых по запросу GET /api/folders/ могли возвращаться некорректные результаты.
6.3.4 – 20.10.2025
Обновили API в рамках подготовки к внедрению новой функциональности.
Исправили ошибки.
6.3.3 – 29.09.2025
Исправили ошибку, из-за которой при отправке поврежденного видео с помощью методов POST /api/instant/folders/ и POST /api/folders/ система возвращала “500 Internal Server Error”. Теперь возвращается “400 Bad Request”.
Обновили API в рамках подготовки к внедрению новой функциональности.
6.3.0 – 05.08.2025
API 6 теперь поддерживает новые: может извлекать из видеороликов, на которых пользователь делает жесты, кадры с действиями.
Вы можете убрать права администратора у пользователя с ролью CLIENT ADMIN, изменив его роль на CLIENT с помощью метода PATCH /api/users/{{user_id}}.
Теперь вы можете создать сервисный токен для пользователя с ролью OPERATOR.
6.2.5 – 18.06.25
Оптимизировали API и улучшили его производительность.
6.2.3 – 02.06.25
Анализы теперь могут выполняться параллельно друг другу. Для включения опции установите значение true параметру OZ_ANALYSE_PARALLELED_CHECK_MEDIA_ENABLED в файле config.py (значение по умолчанию – false).
Вы можете выключить авторизацию для Instant API (режима работы без сохранения данных). Добавьте в файл конфигурации config.py параметр OZ_AUTHORIZE_DISABLED_STATELESS
6.0.1 – 30.04.25
Оптимизировали хранилище и базу данных.
Добавили новый способ отправки данных на анализ: . Этот запрос включает в себя создание папки и назначение анализов в одном и том же запросе – все необходимые данные указываются в payload.
Добавили новый режим работы API, при котором данные запроса и ответа не сохраняются ни локально, ни в какой-либо базе данных. может использоваться и сам по себе, и с другими компонентами API.
5.3.1 – 24.12.2024
Оптимизировали потребление серверных ресурсов при проведении биометрического анализа.
5.3.0 – 21.11.2024
API теперь может извлекать из видеороликов, на которых пользователь делает жесты, кадры с действиями. Доработка выполнена в связи с вводом новых регуляторных требований к биометрической идентификации в Казахстане. Требования к версиям других компонентов описаны .
Подготовили новый шаблон отчета, который также соответствует этим требованиям.
Миниатюры для нового отчета генерируются на основе кадров с действиями.
5.2.0 – 06.09.2024
Обновили коллекцию Postman. Опубликовали новую коллекцию и на .
Добавили метод проверки настроек таймзоны: GET {{host}}/api/config
Добавили параметры к методу GET {{host}}/api/event_sessions:
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
4.0.8-patch1 – 16.07.2024
Обновления безопасности.
4.0.8 – 22.05.2023
Настроили авторотацию логов.
Добавили консольную команду для удаления пользователя.
Генерацию предпросмотра видео теперь можно отключить.
4.0.2 – 13.09.2022
Система теперь удаляет ненужные кадры, оставшиеся после раскадровки видео.
Добавили новые методы GET and POST для media/<media_id>/snapshot/
Заменили шаблон отчета по умолчанию.
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
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.
Добавили настройки валидации пароля.
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.
3.9.0:
Исправили удаление отчетов – теперь они удаляются при удалении их автора.
3.8.1
Поправили доступы – Client теперь может просматривать только свой профиль.
3.8.0
Client Operator теперь может редактировать только свой профиль.
Client больше не может удалять свои заявки, любые медиа, отчеты или анализы.
Client Service может создавать персон в коллекциях и просматривать отчеты в рамках компании.
3.7.1
У ролей Client, Client Admin, Client Operator теперь есть доступы на просмотр профилей пользователя только внутри компании.
Запустили альфа/бета-тестирование.
Теперь поддерживаем заголовок с датой просрочки токена авторизации.
3.7.0
Добавили роль Client Operator – это Client Admin, но без доступа к управлению аккаунтом и компанией.
И Client Admin, и Client Operator могут менять статус анализа.
Создавать, редактировать и удалять что-либо в моделях Collection и CollectionPerson в рамках компании теперь могут только Admin и Client Admin.
Внесены внутренние улучшения.
Повысили безопасность.
и установите ему значение
true
(значение по умолчанию –
false
).
Исправили ошибку, из-за которой видео в MP4 могло не проигрываться после скачивания из SDK.
Для запросов без авторизации теперь возвращается корректная ошибка.
Исправили ошибку, из-за которой временами появлялась ошибка 500. Это происходило, если в видео было слишком мало кадров. Добавили соответствующую проверку и сделали описания ошибок более информативными.
Улучшили производительность, сделали удобнее процесс установки, повысили безопасность.
Теперь можно комбинировать рабочие системы, использующие асинхронные методы или Celery worker (локальная обработка, обработка через Celery). Для каждой из комбинаций добавлена поддержка хранения в S3.
Повысили безопасность.
Прекратили поддержку RAR-архивов.
Временно не поддерживаем Active Directory. В будущих релизах планируем вернуть эту функциональность.
Длительность анализа теперь считается точнее.
Для роли CLIENT заменили флаги is_admin и is_service новыми ролями: CLIENT ADMIN и CLIENT SERVICE соответственно. Для установки роли воспользуйтесь параметром user_type.
Чтобы выписать сервисный токен для пользователя с помощью метода {{host}}/api/authorize/service_token/, убедитесь, что этому пользователю назначена роль CLIENT SERVICE. Токен для другого пользователя с такой ролью можно создать с помощью {{host}}/api/authorize/service_token/{user_id}.
Убрали атрибуты коллекции и персоны из COLLECTION.analysis.
Мы больше не записываем кадры в SHOTS_SET как отдельные объекты. Для сохранения одного из кадров вашего видео вы можете воспользоваться опцией "Лучший кадр".
expire_date в {{host}}/api/authorize/auth и {{host}}/api/authorize/refresh
access_token.exp из payload
session_id в {{host}}/api/authorize/auth и {{host}}/api/authorize/refresh
token_id
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 не мог установить новый пароль для пользователя из своей компании.
.
Архивы RAR больше не поддерживаются.
По умолчанию в analyses.results_media.results_data теперь один параметр: confidence_spoofing. Если для обратной совместимости нужны все три (confidence_replay, confidence_liveness и confidence_spoofing), это можно настроить.
Обновили PDF-отчет, который грузится по умолчанию.
Название PDF-отчета теперь содержит folder_id.
Токен доступа для роли ADMIN теперь действителен 5 лет.
Добавили идентификатор папки folder_id к названию отчета.
Исправили ошибки и оптимизировали работу API.
Превью для набора кадров теперь показывается с исходным соотношением сторон.
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 добавили журналирование.
Обновили алгоритм удаления компании.
Улучшили логику обработки черных списков.
Исправили несколько багов.
для набора изображений – в нем хранятся сумма md5, размер, mime-тип.
Исправили отчет для наборов изображений.
Провели рефакторинг модулей.
Добавили задержки для auth, rest_unauthorized, rps_with_token (OZ_THROTTLING_RATES в настройках, по умолчанию отключено).
Теперь можно проверять доступы пользователя к статичным файлам (OZ_USE_PERMISSIONS_FOR_STATIC в настройках, по умолчанию – False).
Добавили новый подметод для заявки - /delete_pi. С его помощью можно удалить в заявке все персональные данные и связанные с ними анализы.
Поправили баг с продлением авторизации.
Доступ на удаление заявки, медиа из заявки, шаблонов отчетов и их вложений, самих отчетов и анализов теперь есть только у Admin и Client Admin (в рамках компании).
Добавили поддержку модуля распознавания документов для стенделона и Docker.
При создании отчета по заявке теперь проверяются доступы пользователя к шаблонам.
Поправили код статуса, который возвращается при создании коллекции, с 200 на 201.
PATCH users/{{user_id}}/ для смены пароля
POST /api/users/{{user_id}}/change-password
DELETE images|media/<media_id> для удаления фото персоны из коллекции
Роли указываются при создании новых пользователей и созданы для ограничения доступа к API при интеграции с прямым доступом.
ADMIN – Администратор системы. Имеет неограниченный доступ ко всем ресурсам системы через API, кроме принятия решений по анализам;
OPERATOR – Системный оператор. Имеет неограниченный доступ на просмотр заявок и может принимать решения по анализам, с помощью кнопки Принять решение (обычно используется в случае появления OPERATOR_REQUIRED);
CLIENT – Клиентская учетная запись. В рамках своей компании имеет доступ к загрузке медиафайлов, запуску анализов, просмотру результатов в своих папках, выгрузке отчетности по заявке;
is_admin – если установлен, пользователь получает доступ к данным всех пользователей внутри своей компании
CLIENT ADMIN – администратор компании, который может управлять пользователями и аккаунтом своей компании. CLIENT ADMIN может просматривать данные всех пользователей и редактировать их, просматривать статистику, удалять файлы в папках, шаблоны отчетов вместе с вложениями, сами отчеты и отдельные анализы, а также может добавлять шаблоны отчетов и изображения в ЧС.
CLIENT OPERATOR – имеет такие же права, как и OPERATOR, но в рамках своей компании.
CLIENT SERVICE – сервисный аккаунт для автоматических соединений. При авторизации под таким пользователем выдаётся токен с долгим временем жизни (по умолчанию 5 лет). Время жизни токенов для обычных пользователей составляет 15 минут (параметризуется), по умолчанию время жизни токенов продлевается при каждом обращении (параметризуется).
Для версий API < 6.0
В версиях 5.3 и ниже для создания пользователя с правами администратора или сервисного пользователя назначьте ему роль CLIENT и установите true в соответствующем флаге:
is_admin дает пользователю права администратора в рамках своей компании.
Подробное описание уровней доступа приведено ниже.
Компания
Папка
Шаблон отчета
Приложения к шаблону отчета
Отчет
Анализ
Коллекция
Персона
Фото персоны
Пользователь
can_start_analyse_biometry – дополнительный флаг для ограничения доступа к проведению биометрии (по умолчанию разрешено)
can_start_analyse_quality – дополнительный флаг для ограничения доступа к проведению анализов Liveness (по умолчанию разрешено)
is_service предназначен для создания сервисных пользователей учётных записей для входа автоматизированным способом. При авторизации под таким пользователем выдаётся токен с долгим временем жизни (по умолчанию 5 лет). Время жизни токенов для обычных пользователей составляет 15 минут (параметризуется), по умолчанию время жизни токенов продлевается при каждом обращении (параметризуется).
