API 參考文件

SaaS API v0.10.0 完整文件對應頁

API 版本: v1 | 最後更新: 2026-02-25

時間說明

⚠️ 本文檔中涉及規則、執行計劃和統計時間等時間欄位，都是指的設備當地時間，由 device.utcOffset 決定。查詢 API 的 startDate / endDate 參數使用 UTC，前端應自行轉換為設備當地時間顯示。

使用順序

1. 認證   → 生成 API Key
2. 設備   → 建立設備 (RTSP URL) + 設定排程
3. 場景   → 建立場景 (排隊分析配置)
4. 告警   → 設置規則
5. 控制   → 啟動/停止分析（若已設定排程可跳過）
6. 數據   → 查詢歷史紀錄
7. 即時串流 → SSE 接收即時分析結果（可選）
8. 通知   → 設置 Webhook 通知

Base URL

https://api.example.com/api/v1

認證

所有請求必須攜帶認證：

Authorization: Bearer {API_KEY}
Content-Type: application/json

統一響應格式

{
  "success": true,
  "statusCode": 200,
  "message": "Operation completed successfully",
  "data": { },
  "meta": {
    "timestamp": "2026-01-29T10:00:00.000Z",
    "requestId": "req-uuid"
  }
}

欄位	型別	說明
`success`	Boolean	請求是否成功
`statusCode`	Number	HTTP 狀態碼
`message`	String	操作結果訊息
`data`	Object	實際資料內容
`meta`	Object	請求元資料
`meta.timestamp`	String	響應時間 (ISO 8601)
`meta.requestId`	String	請求追蹤 ID

API 端點目錄

模組	說明	連結
API Keys	建立、管理 API 金鑰	查看
設備	設備的 CRUD 操作	查看
場景	場景配置與 ROI 定義	查看
告警	告警規則設定與觸發記錄	查看
分析控制	啟動/停止分析與狀態查詢	查看
數據查詢	快照與滾動統計數據	查看
LLM / VLM API	洞察、摘要、自然語言搜尋與屬性查詢	查看
Billing Dashboard	配額、趨勢、同期對比與預測	查看
Usage API	用戶與設備用量查詢	查看
Admin 配額管理	管理員增額操作	查看
即時串流	SSE 即時接收分析結果	查看
Webhook	通知設定與簽名驗證	查看

補充章節

版本重點（v0.10.0）

新增 Analysis Attributes 獨立 API（/analysis/attributes）
Billing Dashboard 擴充交易紀錄與 device-level 趨勢
Usage API 新增 period=YYYY-MM 查詢
VLM 快照抽樣策略與 Prompt 升級

使用順序

1. 認證   → 生成 API Key
2. 設備   → 建立設備 (RTSP URL) + 設定排程
3. 場景   → 建立場景 (排隊分析配置)
4. 告警   → 設置規則
5. 控制   → 啟動/停止分析（若已設定排程可跳過）
6. 數據   → 查詢歷史紀錄
7. 即時串流 → SSE 接收即時分析結果（可選）
8. 通知   → 設置 Webhook 通知

統一響應格式

{
  "success": true,
  "statusCode": 200,
  "message": "Operation completed successfully",
  "data": { },
  "meta": {
    "timestamp": "2026-01-29T10:00:00.000Z",
    "requestId": "req-uuid"
  }
}

欄位	型別	說明
`success`	Boolean	請求是否成功
`statusCode`	Number	HTTP 狀態碼
`message`	String	操作結果訊息
`data`	Object	實際資料內容
`meta`	Object	請求元資料
`meta.timestamp`	String	響應時間 (ISO 8601)
`meta.requestId`	String	請求追蹤 ID

API 端點目錄

模組	說明	連結
API Keys	建立、管理 API 金鑰	查看
設備	設備的 CRUD 操作	查看
場景	場景配置與 ROI 定義	查看
告警	告警規則設定與觸發記錄	查看
分析控制	啟動/停止分析與狀態查詢	查看
數據查詢	快照與滾動統計數據	查看
LLM / VLM API	洞察、摘要、自然語言搜尋與屬性查詢	查看
Billing Dashboard	配額、趨勢、同期對比與預測	查看
Usage API	用戶與設備用量查詢	查看
Admin 配額管理	管理員增額操作	查看
即時串流	SSE 即時接收分析結果	查看
Webhook	通知設定與簽名驗證	查看