Введение и аутентификация

Базовый путь /api/v1, вход по паролю, статические токены чтения и записи, форма ответов, коды ошибок и пагинация.

Всё, что делает панель управления, делается через REST API — панель не имеет ни одной привилегии, недоступной вам из curl. Здесь описано то, что относится ко всем запросам: как получить токен, как его передавать, как устроены ответы и как читать ошибки. Отдельные группы операций разобраны на страницах Потоки и Конфигурация и система, готовые сценарии — на странице Готовые сценарии.

Базовый путь и порты#

API живёт на том же HTTP-слушателе, что и панель, плеер и медиа — отдельный порт поднимать не нужно.

Дальше в примерах используется переменная окружения BASE — задайте её один раз:

BASE=https://media.example.com

Три вида учётных данных#

Все учётные данные задаются в блоке auth { } файла конфигурации и предъявляются одним и тем же заголовком Authorization: Bearer <ТОКЕН>.

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

Пустое значение любого токена отвергается при проверке конфигурации, как и совпадение api_read_token с api_write_token.

Что не открывает ни один API-токен#

Статический токен никогда не становится ключом к воспроизведению: POST /api/v1/auth/media-grants отвечает ему 403. Доступ к медиа — отдельный уровень, см. Модель доступа.

Вход и получение сессионного токена#

curl -sS -X POST "$BASE/api/v1/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"password":"ваш-пароль-администратора"}'

{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIs…","exp":1787186134}

Поле exp — абсолютный дедлайн в секундах Unix. Время жизни токена — 12 часов. Ключ подписи берётся из session_secret; если он не задан, секрет генерируется случайно при каждом старте, и токены не переживают перезапуск сервиса.

Удобная заготовка для всех остальных примеров:

TOKEN=$(curl -sS -X POST "$BASE/api/v1/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"password":"ваш-пароль-администратора"}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["token"])')

curl -sS "$BASE/api/v1/totals" -H "Authorization: Bearer $TOKEN"

{"streams":10,"sessions":1,"bytes_in":6508772297,"bytes_out":105870921,
 "dvr_sessions":0,"dvr_bytes_out":24412877,"live_sessions":1,"live_bytes_out":81458044}

Ответы входа при неудаче:

Как передавать токен#

Только заголовком. Единственное исключение — поток событий:

# Правильно — всегда и везде:
curl -sS "$BASE/api/v1/streams" -H "Authorization: Bearer $TOKEN"

# Допустимо ТОЛЬКО для /api/v1/events и ТОЛЬКО с сессионным токеном:
curl -sN "$BASE/api/v1/events?topics=totals&token=$TOKEN"

Строку запроса ?token= принимает единственный маршрут — GET /api/v1/events, потому что браузерный EventSource не умеет задавать заголовки. На любом другом маршруте параметр игнорируется и запрос получает 401.

Привязка сессии к адресу#

При auth { admin_ip_bind on; } сессионный токен привязан к IP-адресу, с которого выполнен вход, и отвергается при предъявлении с другого адреса. Реальный адрес берётся из заголовков X-Forwarded-For, Forwarded, X-Real-IP только если непосредственный клиент перечислен в trusted_proxies; иначе используется адрес сокета. За обратным прокси без trusted_proxies все входы будут выглядеть как приходящие с адреса прокси.

Обозначения прав в этой документации#

У каждой операции на страницах API стоит строка с требуемым уровнем:

Чтение — подходят любые учётные данные: сессия администратора, токен записи или токен чтения.

Запись — нужна сессия администратора либо api_write_token; токен чтения получает 403.

Только сессия — принимается исключительно сессионный токен из POST /auth/login; ни один статический токен не подходит.

Идентификатор потока в URL#

Идентификатор потока — непрозрачный путь, который может содержать / (cam1, live/cam1, site-north/entrance/main). Отсюда одно правило, о которое спотыкаются все интеграции:

• В путях /api/v1/… идентификатор передаётся одним percent-encoded сегментом: live%2Fcam1.
• В медиа-URL идентификатор идёт с обычными слэшами: /live/cam1/index.m3u8.

# Поток называется live/cam1
curl -sS "$BASE/api/v1/streams/live%2Fcam1" -H "Authorization: Bearer $TOKEN"   # снимок
curl -sS "$BASE/live/cam1/index.m3u8"                                            # плейлист

Маршруты GET|PATCH|DELETE /streams/{id}, /dvr-archive/{stream} и все маршруты с {name} жёстко отвергают литеральный / в сегменте. Маршруты действий (/start, /stop, /restart, /clone, /config, /timeseries, /sessions) принимают обе формы, но кодировать безопаснее всегда.

Форма ответа: конверта нет там, где вы его ждёте#

Ключ items — не универсальный. Формы ровно три.

Одиночные ресурсы (GET /streams/{id}, GET /system, GET /totals, GET /license) возвращают объект без обёртки.

Пагинация, сортировка и проекция#

Параметры ниже понимают все три пагинированных списка.

curl -sS "$BASE/api/v1/streams?fields=id,health,viewers,bitrate&sort=viewers:desc&limit=3" \
  -H "Authorization: Bearer $TOKEN"

{"items":[{"bitrate":2920000.0,"health":"ok","id":"cam1","viewers":1},
          {"bitrate":14649134.86,"health":"ok","id":"cam2","viewers":1},
          {"bitrate":3455232.76,"health":"ok","id":"cam3","viewers":0}],
 "limit":3,"next_cursor":"18446744073709551615\u001fcam3","page":null,
 "raw_total":10,"total":10,"total_pages":4}

Поле total — сколько строк осталось после фильтров, raw_total — сколько было до них. Значение next_cursor подставляйте в ?cursor= следующего запроса; если оно null — курсорная пагинация для этой сортировки недоступна, листайте через ?page=.

# Первая страница
cur=$(curl -sS "$BASE/api/v1/streams?fields=id&limit=3" -H "Authorization: Bearer $TOKEN" \
  | python3 -c 'import sys,json,urllib.parse; print(urllib.parse.quote(json.load(sys.stdin)["next_cursor"] or "", safe=""))')

# Следующая
curl -sS "$BASE/api/v1/streams?fields=id&limit=3&cursor=$cur" -H "Authorization: Bearer $TOKEN"

Условные запросы#

Списки потоков и счётчики снабжены ETag. Присылайте If-None-Match — при совпадении сервер ответит 304 и не будет строить тело.

Ошибки#

Форм ошибок три, и они не смешиваются.

1. application/problem+json — все 404 на /api/* и все ошибки изменяющих операций:

{"type":"about:blank","title":"Not Found","status":404,"instance":"/api/v1/streams/nosuchstream"}

Поле type всегда about:blank, title — короткая машинно-стабильная формулировка, detail — пояснение для человека (у чтений отсутствует).

2. application/json {"error":"<тег>"} — маршруты /auth/* и любой отказ гейта:

{"error":"unauthorized"}

3. Короткий text/plain — только медиа-маршруты; плееры не читают тело.

Коды, которые вернёт любая операция#

Ограничения транспорта#

Машиночитаемая спецификация#

Полная спецификация OpenAPI 3.1 со всеми 71 операцией, схемами тел, примерами и кодами ответов:

openapi.yaml — скачать

Страницы этого раздела описывают операции над потоками, конфигурацией и системой. Всё остальное — сессии целиком, шаблоны, библиотеки VoD, обслуживание архива, кластер и действия узла — есть в спецификации; её можно открыть в любом просмотрщике OpenAPI или скормить генератору клиента.

Куда дальше#

• Потоки — весь жизненный цикл потока через API.
• Конфигурация и система — чтение и запись конфигурации, лицензия, журналы.
• Готовые сценарии — рабочие рецепты на curl и Python.
• Доступ к админке и API — как устроен гейт со стороны конфигурации.