# Ключевые понятия Oz API

Oz API обеспечивает полноценный REST API-интерфейс для биометрии лица: как сравнения лиц, так и Liveness-проверок. В этой статье описаны основные концепции Oz API.

### Аутентификация, роли пользователей и управление доступом

В целях безопасности каждый вызов Oz API требует наличия в заголовке токена доступа. Чтобы получить этот токен, вызовите метод `POST /api/authorize/auth` с полученными от нас логином и паролем. В ответе вы получите токен доступа. Его нужно будет указывать в заголовке `X-Forensics-Access-Token` во всех последующих вызовах методов Oz API. Подробнее процесс аутентификации описан [здесь](/oz-knowledge-ru/rukovodstva/rukovodstvo-razrabotchika/api/oz-api/autentifikaciya-i-obrabotka-dannykh/tokens.md).

Для пользователей системы есть набор ролей, различающихся по предоставляемым возможностям: от роли `CLIENT`, которая дает возможность проводить проверки и скачивать отчеты без прав администратора, до `ADMIN` с полным доступом практически ко всем объектам системы. Детальная информация по ролям находится [здесь](/oz-knowledge-ru/rukovodstva/rukovodstvo-razrabotchika/api/oz-api/user-roles.md).

### Сохранение данных

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

<figure><img src="/files/s1yx1dHOkPHcEPoFrvUt" alt=""><figcaption></figcaption></figure>

### Типы медиафайлов и теги

Oz API работает и с фото-, и с видеофайлами. Видео при этом может быть как файлом в «обычном» понимании, то есть контейнером в формате MP4 или MOV, так и последовательностью кадров в ZIP-архиве. Чтобы определить тип медиафайла, Oz API использует MIME-тип файла.

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

* `photo_id_front` – для лицевой стороны документа
* `photo_selfie` – для референтного фото, не являющегося документом
* `video_selfie_blank` – для Liveness-видео, снятого не средствами Oz Liveness SDK
* если фото или видео снято средствами нашего SDK, теги выставляются автоматически

### Асинхронные анализы

Поскольку анализ видео может занять несколько секунд, анализы проводятся асинхронно. Сначала вы запускаете анализ (`POST /api/folders/{{folder_id}}/analyses/`), а затем следите за результатами, периодически запрашивая их с сервера, пока обработка не закончится (`GET /api/analyses/{{analyse_id}}` для определенного анализа или `GET /api/folders/{{folder_id}}/analyses/` для всех анализов, назначенных на папку). Кроме того, можно использовать вебхуки. С примером опроса и использования вебхука можно ознакомиться [здесь](/oz-knowledge-ru/rukovodstva/rukovodstvo-razrabotchika/api/oz-api/use-cases/liveness.md).&#x20;

Более детальная информация о возможностях Oz API содержится в [соответствующей секции нашего руководства разработчика](/oz-knowledge-ru/rukovodstva/rukovodstvo-razrabotchika/api/oz-api.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.ozforensics.com/oz-knowledge-ru/obshaya-informaciya/readme/klyuchevye-ponyatiya-oz-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.