Перейти до основного вмісту

Довідник із REST API

Insight надає площину керування, якою користується браузер, як HTTP API. За його допомогою можна автоматизувати перевірки стану, імпорт медіа, налаштування потокових джерел, виявлення переглядача, огляд робочого простору та діагностику середовища виконання.

Запущена служба публікує дві кінцеві точки документації API:

  • GET /api/docs відкриває інтерактивний інтерфейс Swagger UI.
  • GET /api/openapi.json повертає документ OpenAPI 3.1 для генерації клієнтів та інших інструментів.

Для типової локальної інсталяції відкрийте:

https://127.0.0.1:9900/api/docs

Insight зазвичай використовує локально згенерований сертифікат для розробки. Клієнтам командного рядка може знадобитися довіряти цьому сертифікату або використовувати -k для локальної діагностики:

curl -k https://127.0.0.1:9900/api/health
curl -k https://127.0.0.1:9900/api/openapi.json -o neat-insight-openapi.json

Типовий сценарій автоматизації​

Завантажте файл, призначте його слоту джерела та запустіть відтворення:

curl -k -F "file=@person_clip.mp4" \
  https://<INSIGHT_HOST>:9900/api/upload/media

curl -k -H "Content-Type: application/json" \
  -d '{"index":1,"file":"person_clip.mp4"}' \
  https://<INSIGHT_HOST>:9900/api/mediasrc/assign

curl -k -H "Content-Type: application/json" \
  -d '{"index":1}' \
  https://<INSIGHT_HOST>:9900/api/mediasrc/start

Щоб транслювати з іншою частотою кадрів, додайте fps до призначення та за бажанням стежте за кодуванням:

curl -k -H "Content-Type: application/json" -d '{"index":1,"file":"person_clip.mp4","fps":15}' https://localhost:9900/api/mediasrc/assign
curl -k -N -H "Content-Type: application/json" -d '{"index":1}' https://localhost:9900/api/mediasrc/prepare
curl -k -H "Content-Type: application/json" -d '{"index":1}' https://localhost:9900/api/mediasrc/start

prepare передає потоком рядки progress <seconds>/<total> (поки кодується інша перекодована версія, перед ними повторюються рядки Waiting for another rendition to finish encoding…; Insight кодує лише одну версію за раз) і завершується рядком Rendition ready: …, Reusing rendition: … або Error: …. Якщо prepare пропущено, start виконує ту саму підготовку без виводу. GET /api/mediasrc/renditions повідомляє, скільки місця на диску займають кешовані перекодовані версії; POST /api/mediasrc/renditions/clear видаляє кешовані перекодовані версії, які не використовує жодне джерело, що відтворюється.

Перш ніж змінювати призначення або стан відтворення, прочитайте /api/mediasrc. За можливості зупиняйте активні джерела, перш ніж видаляти їхні медіафайли.

Слот, у який публікує потік не Insight, а інший застосунок, повідомляє state: "external" з об’єктом external (протокол, адреса, час початку публікації, підтримка кодека, розміри кадру, бітрейт); кожен слот також містить список своїх поточних readers. Для такого слота start і assign повертають 409, так само як і stop, коли на слоті не залишилося жодного власного потоку Insight; POST /api/mediasrc/takeover від’єднує відправника. Групові операції залишають зовнішній потік запущеним і перелічують такі слоти в skipped_external; reset однаково очищає збережений запис кожного слота. GET /stream/preview/src<N>.mjpg відтворює попередній перегляд MJPEG будь-якого активного слота з частотою кадрів джерела.

POST /api/mediasrc/pull з {"index": 3, "url": "rtsp://192.168.1.10:554/stream1", "username": "admin", "password": "…"} підтягує наявний потік RTSP/RTSPS у слот; після цього слот повідомляє state: "pulled" з об’єктом pull (status зі значенням connecting, live, unreachable або auth_failed, а також схема, хост, шлях, помилка, час початку, підтримка кодека, розміри кадру, частота кадрів і бітрейт; облікові дані — ніколи). У разі відхилення облікових даних повертається 400 з "reason": "auth_failed"; слот, який транслює, є зовнішнім, джерелом вебкамери або вже підтягнутим, повертає 409, а 502 означає, що mediamtx відхилив налаштування або був недоступний. stop звільняє підтягнутий потік. Для підтягнутого слота assign, assign-webcam, start, prepare і takeover повертають 409. stop-all і reset також звільняють підтягнуті потоки й перелічують їх у stopped_pulled; auto-assign-all і start-bulk пропускають підтягнутий слот і перелічують його в skipped_pulled. Підтягнуті потоки існують лише протягом сеансу.

Правила відповідей і потокової передачі​

  • Більшість кінцевих точок повертають JSON. Для помилок зазвичай використовується {"error": "message"} разом із кодом помилки HTTP.
  • Завантаження та імпорт повертають потоковий перебіг виконання у форматі text/plain, а не один об’єкт JSON.
  • /api/neat-metrics — це потік подій, що надсилаються сервером (server-sent events).
  • Кінцеві точки попереднього перегляду MJPEG і джерел повертають багатокомпонентні (multipart) потоки зображень.
  • Кінцеві точки необроблених файлів медіа та робочого простору повертають запитаний двійковий вміст.

Інтерфейс Swagger UI використовує той самий хост, що й Insight, тому його запити Try it out (Спробувати) спрямовуються на поточну інсталяцію. Такі операції, як видалення, скидання, запуск і зупинка, негайно змінюють стан служби.

Групи API​

Документ OpenAPI групує операції за призначенням:

  • Service and system (служба та система) — стан, середовище, відомості про збірку, метрики, журнали та додаткові інструменти.
  • Diagnostics (діагностика) — прийом RTP, вихідний потік WebRTC і метрики, що надсилаються сервером.
  • Media library and imports (медіатека та імпорт) — каталог, YouTube, завантаження, видалення, перевірка, попередній перегляд і звантаження.
  • Media sources (джерела медіа) — призначення та керування відтворенням RTSP/HTTP.
  • Viewer (переглядач) — URL переглядача, доступний із браузера, і налаштована кількість каналів.
  • Workspace (робочий простір) — перегляд, пошук, огляд і попередній перегляд файлів робочого простору та елементів архівів MPK.
  • DevKit shell (оболонка DevKit) — виявлення й запуск розміщеного мосту оболонки, якщо його налаштовано.
  • Board (плата) — вибір плати, яку використовують функції для роботи з платою, перевірка з’єднання SSH і довіра до ключа хоста перепрошитої плати.
  • Peripherals (периферійні пристрої) — перелік камер MIPI та USB і мікрофонів ALSA, про які повідомляє SiMa Sentinel на вибраній платі, запуск, перевірка, потокова передача й зупинка тимчасового попереднього перегляду камери, а також перевірка мікрофона через API.
  • Sentinel — перевірка наявності та встановлення SiMa Sentinel на вибраній платі, читання телеметрії плати, запуск і зупинка трасувань, а також перелік, перегляд, видалення й порівняння збережених запусків.

Необроблений файл OpenAPI також підтримується в репозиторії Insight за шляхом neat_insight/openapi.json. Тести порівнюють його операції із зареєстрованими у Flask маршрутами /api, тож нові кінцеві точки не можна додати непомітно, не оновивши довідник.