跳至主要内容

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；當插槽上已沒有 Insight 自己的串流時，stop 也會如此。POST /api/mediasrc/takeover 會中斷發布端的連線。批次作業會讓外部串流繼續執行，並在 skipped_external 中列出這些插槽；reset 仍會清除每個插槽的已儲存記錄。GET /stream/preview/src<N>.mjpg 會以來源幀率呈現任何即時插槽的 MJPEG 預覽。

使用 {"index": 3, "url": "rtsp://192.168.1.10:554/stream1", "username": "admin", "password": "…"} 呼叫 POST /api/mediasrc/pull，會將現有的 RTSP/RTSPS 串流拉取到插槽中；之後插槽會回報 state: "pulled" 以及 pull 物件（status 為 connecting、live、unreachable 或 auth_failed，另含協定、主機、路徑、錯誤、開始時間、編解碼器支援情況、畫面尺寸、幀率和位元率；絕不包含認證資訊）。認證資訊遭拒時會回傳 400 並附上 "reason": "auth_failed"；正在串流、屬於外部、為網路攝影機來源或已拉取的插槽會回傳 409，502 表示 mediamtx 拒絕了設定或無法連線到 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 是一種由伺服器推送的事件串流。
  • MJPEG 預覽和來源端點會傳回多部分影像串流。
  • 媒體和工作區的原始檔案端點會傳回所要求的二進位內容。

Swagger UI 使用與 Insight 相同的主機，因此其 Try it out（試用）請求會指向目前的安裝環境。刪除、重設、啟動和停止等操作會立即變更服務狀態。

API 群組​

OpenAPI 文件會依用途將操作分組：

  • 服務與系統 — 健康狀況、環境、建置細節、指標、日誌，以及可選的工具。
  • 診斷 — RTP 輸入、WebRTC 輸出，以及伺服器推送的指標。
  • 媒體庫和匯入 — 目錄、YouTube、上傳、刪除、檢視、預覽和下載。
  • 媒體來源 — 指派以及 RTSP/HTTP 播放控制。
  • 檢視器 — 可透過瀏覽器存取的檢視器網址，以及已設定的頻道容量。
  • 工作區 — 瀏覽、搜尋、檢查和預覽工作區檔案以及 MPK 封存檔中的成員。
  • DevKit shell — 在已設定時，探索並啟動託管的 shell 橋接。
  • 開發板 — 選取開發板導向功能所使用的開發板、測試 SSH 連線，並信任重新燒錄之開發板的主機金鑰。
  • 周邊裝置 — 列出 SiMa Sentinel 在選取的開發板上回報的 MIPI 和 USB 相機及 ALSA 麥克風，啟動、檢查、串流或停止暫時性的相機預覽，並透過 API 測試麥克風。
  • Sentinel — 檢查並在選取的開發板上安裝 SiMa Sentinel、讀取開發板的遙測資料、開始和停止追蹤，以及列出、檢視、刪除和比較已儲存的執行記錄。

原始的 OpenAPI 檔案也保存在 Insight 儲存庫的 neat_insight/openapi.json 中。測試會將其操作與 Flask 註冊的 /api 路由進行比較，因此無法在不更新參考資料的情況下悄悄新增端點。