設備 API

設備是指連接到系統的視頻來源，通常是 IP Camera 或 RTSP 串流。

對齊版本：SaaS-API v0.10.0（2026-02-25）

端點概覽

方法	路徑	說明
POST	`/api/v1/devices`	建立設備
GET	`/api/v1/devices`	查詢設備列表
GET	`/api/v1/devices/{id}`	取得設備詳情
GET	`/api/v1/devices/{id}/scenes`	取得設備場景列表
PATCH	`/api/v1/devices/{id}`	更新設備
DELETE	`/api/v1/devices/{id}`	刪除設備
POST	`/api/v1/devices/{id}/probe`	手動探測設備 RTSP 連線
GET	`/api/v1/devices/{id}/quota`	取得設備配額狀態
PATCH	`/api/v1/devices/{id}/quota`	更新設備配額限制

使用場景

攝影機註冊：將 IP 攝影機/NVR 的 RTSP 串流註冊到系統
設備管理：統一管理多個視訊來源
排程自動化：建立/更新設備時同時設定每日自動啟停分析的時段
連線探測：手動觸發 RTSP 探測，讓離線設備重新上線
配額管理：監控設備分析時數與功能配額使用狀況

建立設備

POST /api/v1/devices

請求參數

參數	型別	必填	範圍/限制	說明
`name`	String	✅	1-200 字元	設備名稱
`description`	String	❌	最大 500 字元	設備描述
`rtspUrl`	String	✅	rtsp:// 或 rtsps://	RTSP 串流 URL
`rtspUsername`	String	❌	-	RTSP 認證帳號 (Basic Auth)
`rtspPassword`	String	❌	-	RTSP 認證密碼 (Basic Auth)
`rtspToken`	String	❌	-	RTSP Bearer Token (Token Auth)
`locationLabel`	String	❌	最大 200 字元	設備位置標籤
`latitude`	Number	❌	-90 ~ 90	WGS84 緯度
`longitude`	Number	❌	-180 ~ 180	WGS84 經度
`geoSource`	String	❌	manual / address / device / ip	地理座標來源
`type`	String (enum)	❌	ip_camera / rtsp_source / usb_camera	設備類型，預設 `ip_camera`
`plan`	String (enum)	❌	level_01 / level_02	方案等級，預設 `level_01`
`tags`	String[]	❌	-	分類標籤
`utcOffset`	String	❌	UTC+H / UTC-H / UTC+H:MM	設備時區 UTC 偏移量，預設 `UTC+0`
`schedule`	Object	❌	-	分析排程

RTSP 認證方式（二擇一）

方式	欄位	說明
Basic Auth	`rtspUsername` + `rtspPassword`	帳號密碼認證
Token Auth	`rtspToken`	Bearer Token 認證

方案等級

方案	每月分析時數	每月告警次數（次/月）	屬性偵測（次/月）	VLM 分析（tokens/月）	enabledCapabilities
`level_01`	150 小時	3,000 次	❌	❌	`["result", "alert"]`
`level_02`	250 小時	5,000 次	5,000 次	10,000,000 tokens	`["result", "alert", "attribute", "vlm"]`

功能項目	`level_01` (基礎版)	`level_02` (進階版)
分析時數	150 小時/月（540,000 秒）	250 小時/月（900,000 秒）
告警配額	3,000 次/月	5,000 次/月
屬性分析	❌ 不支援	✅ 5,000 次/月
VLM 分析	❌ 不支援	✅ 10,000,000 tokens/月

ℹ️ 以上數值對齊後端 DEVICE_PLAN_QUOTAS（level_01 / level_02）。 ℹ️ level_02 的 5,000 是「屬性偵測次數」；VLM 單位是 tokens，不是次數。

💡 配額重置：每月 1 日 00:00 UTC 重置，不累積不結轉。

⚠️ 超額處理：

分析時數耗盡 → 自動停止分析，觸發 quota_exceeded Webhook

告警配額耗盡 → 分析繼續，但不再觸發新告警

屬性偵測配額耗盡 → 分析繼續，attribute 消息丟棄不寫入

VLM token 耗盡 → 分析繼續，不再觸發 VLM 深度分析

80% 用量時觸發 quota_warning Webhook

enabledCapabilities

功能	說明	Topic/輸出
`result`	分析結果輸出	`scene-analysis-results`
`alert`	告警評估與觸發	`scene-analysis-alerts`
`attribute`	行人屬性偵測	`scene-analysis-attributes` (v1.7.0+)
`vlm`	VLM 摘要與結構化輸出	`vlmStructuredResult`, `vlmSummary`

UTC 偏移量範例

UTC+8（台北、新加坡）
UTC-5（美東標準時間）
UTC+5:30（印度）
UTC+0（預設）

排程結構 (Schedule)

欄位	型別	必填	說明
`daylightSaving`	Boolean	❌	是否啟用日光節約時間，預設 `false`
`dailySlots`	Number[]	✅	每日啟用的時段索引 (0-47)，最多 48 個
`dailyPeakSlots`	Number[]	❌	每日高峰時段索引（用於告警推送頻率）
`weeklySlots`	Number[][]	❌	按週幾區分的時段（7 組，週日到週六），非空時覆蓋 `dailySlots`
`weeklyPeakSlots`	Number[][]	❌	按週幾區分的高峰時段索引

每日分為 48 個時段（每時段 30 分鐘），基於設備 utcOffset 換算：

Slot 範圍	時間範圍	常見用途
0-11	00:00-05:59	深夜/凌晨
12-15	06:00-07:59	早班前
16-23	08:00-11:59	上午營業
24-27	12:00-13:59	午餐時段
28-35	14:00-17:59	下午營業
36-43	18:00-21:59	晚間營業
44-47	22:00-23:59	營業結束

💡 schedule 不提供或設為 null 表示不啟用排程，需手動啟動/停止分析。

請求範例

{
  "name": "大門入口攝影機",
  "description": "監控大樓正門入口區域",
  "rtspUrl": "rtsp://192.168.1.100:554/stream1",
  "rtspUsername": "admin",
  "rtspPassword": "password123",
  "locationLabel": "A棟 1F 大門",
  "type": "ip_camera",
  "plan": "level_01",
  "tags": ["entrance", "building-a"],
  "utcOffset": "UTC+8",
  "schedule": {
    "daylightSaving": false,
    "dailySlots": [16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43]
  }
}

💡 上述 schedule 表示 UTC+8 時區（台北）08:00-22:00

更新設備

PATCH /api/v1/devices/{id}

所有建立時的欄位皆可更新。schedule 設為 null 可停用排程。

⚠️ 更改 plan 會影響當月剩餘額度計算，建議在月初設定。

查詢設備列表

GET /api/v1/devices

Query 參數

參數	型別	預設	說明
`page`	Number	1	頁碼
`limit`	Number	20	每頁數量 (1-100)
`q`	String	-	全文搜尋（名稱、位置、描述）
`sort`	String	createdAt	排序欄位
`order`	String	DESC	ASC / DESC
`filters[id]`	UUID	-	設備 ID
`filters[name]`	String	-	設備名稱
`filters[description]`	String	-	設備描述
`filters[locationLabel]`	String	-	設備位置標籤
`filters[status]`	String (enum)	-	active / paused / archived
`filters[onlineStatus]`	String (enum)	-	online / offline / unknown
`filters[type]`	String (enum)	-	ip_camera / rtsp_source / usb_camera
`filters[rtspUrl]`	String	-	RTSP URL
`filters[userId]`	UUID	-	擁有者 ID
`filters[lastHeartbeatAt]`	DateTime	-	最後心跳時間
`filters[totalAnalysisCount]`	Number	-	分析總次數
`filters[totalProcessingTimeSeconds]`	Number	-	處理總秒數
`filters[createdAt]`	DateTime	-	建立時間
`filters[updatedAt]`	DateTime	-	更新時間

取得設備詳情

GET /api/v1/devices/{id}

回傳設備完整資訊，含 plan、utcOffset、schedule、onlineStatus。

取得設備場景列表

GET /api/v1/devices/{id}/scenes

權限: device:read + scene:read

取得特定設備下所有配置的場景（分頁）。

Query 參數

參數	型別	預設	說明
`page`	Number	1	頁碼
`limit`	Number	20	每頁數量

響應 (200)

回傳分頁場景列表，格式同場景 API 的查詢列表響應。

錯誤代碼

HTTP 狀態	說明
404	設備不存在

刪除設備

DELETE /api/v1/devices/{id}

回應: 204 No Content

級聯行為：刪除設備時會自動級聯軟刪除：

該設備所有場景的告警規則
該設備的所有場景
該設備的所有設備 API 金鑰
設備本身

⚠️ 設備分析處於 RUNNING / STARTING / STOPPING 狀態時無法刪除，需先停止分析。

手動探測設備

POST /api/v1/devices/{id}/probe

手動觸發 RTSP 連線探測，主要用於讓 offline 狀態的設備重新上線。

探測狀態規則

狀態	自動探測（每 60 秒）	手動探測	說明
`online`	✅	✅	正常運作
`unknown`	✅	✅	首次探測或重啟後
`offline`	❌	✅	僅能透過手動探測恢復

💡 連續 3 次自動探測失敗後，設備標記為 offline 並停止自動探測。

錯誤代碼

errorCode	說明	建議處理
`CONNECTION_TIMEOUT`	連線超時（5 秒）	檢查網路連通性、防火牆
`CONNECTION_REFUSED`	連線被拒絕	檢查 RTSP 埠號
`AUTH_FAILED`	認證失敗	檢查帳號密碼或 Token
`AUTH_REQUIRED`	需要認證	設定認證資訊
`INVALID_URL`	URL 格式錯誤	檢查 rtspUrl
`UNKNOWN_ERROR`	未知錯誤	聯繫技術支援

設備配額

GET /api/v1/devices/{id}/quota

取得設備當月配額使用狀況。

響應範例

{
  "success": true,
  "data": {
    "deviceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "period": "2026-02",
    "quotaSeconds": 540000,
    "usedSeconds": 18000,
    "remainingSeconds": 522000,
    "usagePercentage": 3.33,
    "hasIndividualLimit": true,
    "isExceeded": false,
    "alertQuota": {
      "featureType": "alert",
      "unit": "count",
      "limit": 3000,
      "used": 150,
      "remaining": 2850,
      "isExceeded": false,
      "isDisabled": false,
      "isUnlimited": false,
      "usagePercentage": 5
    },
    "attributeQuota": {
      "featureType": "attribute",
      "unit": "count",
      "limit": 0,
      "used": 0,
      "remaining": 0,
      "isExceeded": false,
      "isDisabled": true,
      "isUnlimited": false,
      "usagePercentage": 0
    },
    "vlmQuota": {
      "featureType": "vlm",
      "unit": "tokens",
      "limit": 0,
      "used": 0,
      "remaining": 0,
      "isExceeded": false,
      "isDisabled": true,
      "isUnlimited": false,
      "usagePercentage": 0
    }
  }
}

功能配額欄位（FeatureQuotaStatus）

欄位	說明
`featureType`	功能類型 (`alert` / `attribute` / `vlm`)
`unit`	計量單位 (`seconds` / `count` / `tokens`)
`limit`	配額上限（0 = 禁用，-1 = 無上限）
`used`	已使用數量
`remaining`	剩餘可用數量
`isExceeded`	是否超限
`isDisabled`	是否禁用（`limit = 0`）
`isUnlimited`	是否無上限（`limit = -1`）
`usagePercentage`	使用百分比

更新配額限制

PATCH /api/v1/devices/{id}/quota

參數	型別	說明
`quotaSeconds`	Number 或 null	設備配額（秒），null = 無上限

設備 API

設備是指連接到系統的視頻來源，通常是 IP Camera 或 RTSP 串流。

對齊版本：SaaS-API v0.10.0（2026-02-25）

端點概覽

方法	路徑	說明
POST	`/api/v1/devices`	建立設備
GET	`/api/v1/devices`	查詢設備列表
GET	`/api/v1/devices/{id}`	取得設備詳情
GET	`/api/v1/devices/{id}/scenes`	取得設備場景列表
PATCH	`/api/v1/devices/{id}`	更新設備
DELETE	`/api/v1/devices/{id}`	刪除設備
POST	`/api/v1/devices/{id}/probe`	手動探測設備 RTSP 連線
GET	`/api/v1/devices/{id}/quota`	取得設備配額狀態
PATCH	`/api/v1/devices/{id}/quota`	更新設備配額限制

使用場景

攝影機註冊：將 IP 攝影機/NVR 的 RTSP 串流註冊到系統
設備管理：統一管理多個視訊來源
排程自動化：建立/更新設備時同時設定每日自動啟停分析的時段
連線探測：手動觸發 RTSP 探測，讓離線設備重新上線
配額管理：監控設備分析時數與功能配額使用狀況

建立設備

POST /api/v1/devices

請求參數

參數	型別	必填	範圍/限制	說明
`name`	String	✅	1-200 字元	設備名稱
`description`	String	❌	最大 500 字元	設備描述
`rtspUrl`	String	✅	rtsp:// 或 rtsps://	RTSP 串流 URL
`rtspUsername`	String	❌	-	RTSP 認證帳號 (Basic Auth)
`rtspPassword`	String	❌	-	RTSP 認證密碼 (Basic Auth)
`rtspToken`	String	❌	-	RTSP Bearer Token (Token Auth)
`locationLabel`	String	❌	最大 200 字元	設備位置標籤
`latitude`	Number	❌	-90 ~ 90	WGS84 緯度
`longitude`	Number	❌	-180 ~ 180	WGS84 經度
`geoSource`	String	❌	manual / address / device / ip	地理座標來源
`type`	String (enum)	❌	ip_camera / rtsp_source / usb_camera	設備類型，預設 `ip_camera`
`plan`	String (enum)	❌	level_01 / level_02	方案等級，預設 `level_01`
`tags`	String[]	❌	-	分類標籤
`utcOffset`	String	❌	UTC+H / UTC-H / UTC+H:MM	設備時區 UTC 偏移量，預設 `UTC+0`
`schedule`	Object	❌	-	分析排程

RTSP 認證方式（二擇一）

方式	欄位	說明
Basic Auth	`rtspUsername` + `rtspPassword`	帳號密碼認證
Token Auth	`rtspToken`	Bearer Token 認證

方案等級

方案	每月分析時數	每月告警次數（次/月）	屬性偵測（次/月）	VLM 分析（tokens/月）	enabledCapabilities
`level_01`	150 小時	3,000 次	❌	❌	`["result", "alert"]`
`level_02`	250 小時	5,000 次	5,000 次	10,000,000 tokens	`["result", "alert", "attribute", "vlm"]`

功能項目	`level_01` (基礎版)	`level_02` (進階版)
分析時數	150 小時/月（540,000 秒）	250 小時/月（900,000 秒）
告警配額	3,000 次/月	5,000 次/月
屬性分析	❌ 不支援	✅ 5,000 次/月
VLM 分析	❌ 不支援	✅ 10,000,000 tokens/月

ℹ️ 以上數值對齊後端 DEVICE_PLAN_QUOTAS（level_01 / level_02）。 ℹ️ level_02 的 5,000 是「屬性偵測次數」；VLM 單位是 tokens，不是次數。

💡 配額重置：每月 1 日 00:00 UTC 重置，不累積不結轉。

⚠️ 超額處理：

分析時數耗盡 → 自動停止分析，觸發 quota_exceeded Webhook

告警配額耗盡 → 分析繼續，但不再觸發新告警

屬性偵測配額耗盡 → 分析繼續，attribute 消息丟棄不寫入

VLM token 耗盡 → 分析繼續，不再觸發 VLM 深度分析

80% 用量時觸發 quota_warning Webhook

enabledCapabilities

功能	說明	Topic/輸出
`result`	分析結果輸出	`scene-analysis-results`
`alert`	告警評估與觸發	`scene-analysis-alerts`
`attribute`	行人屬性偵測	`scene-analysis-attributes` (v1.7.0+)
`vlm`	VLM 摘要與結構化輸出	`vlmStructuredResult`, `vlmSummary`

UTC 偏移量範例

UTC+8（台北、新加坡）
UTC-5（美東標準時間）
UTC+5:30（印度）
UTC+0（預設）

排程結構 (Schedule)

欄位	型別	必填	說明
`daylightSaving`	Boolean	❌	是否啟用日光節約時間，預設 `false`
`dailySlots`	Number[]	✅	每日啟用的時段索引 (0-47)，最多 48 個
`dailyPeakSlots`	Number[]	❌	每日高峰時段索引（用於告警推送頻率）
`weeklySlots`	Number[][]	❌	按週幾區分的時段（7 組，週日到週六），非空時覆蓋 `dailySlots`
`weeklyPeakSlots`	Number[][]	❌	按週幾區分的高峰時段索引

每日分為 48 個時段（每時段 30 分鐘），基於設備 utcOffset 換算：

Slot 範圍	時間範圍	常見用途
0-11	00:00-05:59	深夜/凌晨
12-15	06:00-07:59	早班前
16-23	08:00-11:59	上午營業
24-27	12:00-13:59	午餐時段
28-35	14:00-17:59	下午營業
36-43	18:00-21:59	晚間營業
44-47	22:00-23:59	營業結束

💡 schedule 不提供或設為 null 表示不啟用排程，需手動啟動/停止分析。

請求範例

{
  "name": "大門入口攝影機",
  "description": "監控大樓正門入口區域",
  "rtspUrl": "rtsp://192.168.1.100:554/stream1",
  "rtspUsername": "admin",
  "rtspPassword": "password123",
  "locationLabel": "A棟 1F 大門",
  "type": "ip_camera",
  "plan": "level_01",
  "tags": ["entrance", "building-a"],
  "utcOffset": "UTC+8",
  "schedule": {
    "daylightSaving": false,
    "dailySlots": [16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43]
  }
}

💡 上述 schedule 表示 UTC+8 時區（台北）08:00-22:00

更新設備

PATCH /api/v1/devices/{id}

所有建立時的欄位皆可更新。schedule 設為 null 可停用排程。

⚠️ 更改 plan 會影響當月剩餘額度計算，建議在月初設定。

查詢設備列表

GET /api/v1/devices

Query 參數

參數	型別	預設	說明
`page`	Number	1	頁碼
`limit`	Number	20	每頁數量 (1-100)
`q`	String	-	全文搜尋（名稱、位置、描述）
`sort`	String	createdAt	排序欄位
`order`	String	DESC	ASC / DESC
`filters[id]`	UUID	-	設備 ID
`filters[name]`	String	-	設備名稱
`filters[description]`	String	-	設備描述
`filters[locationLabel]`	String	-	設備位置標籤
`filters[status]`	String (enum)	-	active / paused / archived
`filters[onlineStatus]`	String (enum)	-	online / offline / unknown
`filters[type]`	String (enum)	-	ip_camera / rtsp_source / usb_camera
`filters[rtspUrl]`	String	-	RTSP URL
`filters[userId]`	UUID	-	擁有者 ID
`filters[lastHeartbeatAt]`	DateTime	-	最後心跳時間
`filters[totalAnalysisCount]`	Number	-	分析總次數
`filters[totalProcessingTimeSeconds]`	Number	-	處理總秒數
`filters[createdAt]`	DateTime	-	建立時間
`filters[updatedAt]`	DateTime	-	更新時間

取得設備詳情

GET /api/v1/devices/{id}

回傳設備完整資訊，含 plan、utcOffset、schedule、onlineStatus。

取得設備場景列表

GET /api/v1/devices/{id}/scenes

權限: device:read + scene:read

取得特定設備下所有配置的場景（分頁）。

Query 參數

參數	型別	預設	說明
`page`	Number	1	頁碼
`limit`	Number	20	每頁數量

響應 (200)

回傳分頁場景列表，格式同場景 API 的查詢列表響應。

錯誤代碼

HTTP 狀態	說明
404	設備不存在

刪除設備

DELETE /api/v1/devices/{id}

回應: 204 No Content

級聯行為：刪除設備時會自動級聯軟刪除：

該設備所有場景的告警規則
該設備的所有場景
該設備的所有設備 API 金鑰
設備本身

⚠️ 設備分析處於 RUNNING / STARTING / STOPPING 狀態時無法刪除，需先停止分析。

手動探測設備

POST /api/v1/devices/{id}/probe

手動觸發 RTSP 連線探測，主要用於讓 offline 狀態的設備重新上線。

探測狀態規則

狀態	自動探測（每 60 秒）	手動探測	說明
`online`	✅	✅	正常運作
`unknown`	✅	✅	首次探測或重啟後
`offline`	❌	✅	僅能透過手動探測恢復

💡 連續 3 次自動探測失敗後，設備標記為 offline 並停止自動探測。

錯誤代碼

errorCode	說明	建議處理
`CONNECTION_TIMEOUT`	連線超時（5 秒）	檢查網路連通性、防火牆
`CONNECTION_REFUSED`	連線被拒絕	檢查 RTSP 埠號
`AUTH_FAILED`	認證失敗	檢查帳號密碼或 Token
`AUTH_REQUIRED`	需要認證	設定認證資訊
`INVALID_URL`	URL 格式錯誤	檢查 rtspUrl
`UNKNOWN_ERROR`	未知錯誤	聯繫技術支援

設備配額

GET /api/v1/devices/{id}/quota

取得設備當月配額使用狀況。

響應範例

{
  "success": true,
  "data": {
    "deviceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "period": "2026-02",
    "quotaSeconds": 540000,
    "usedSeconds": 18000,
    "remainingSeconds": 522000,
    "usagePercentage": 3.33,
    "hasIndividualLimit": true,
    "isExceeded": false,
    "alertQuota": {
      "featureType": "alert",
      "unit": "count",
      "limit": 3000,
      "used": 150,
      "remaining": 2850,
      "isExceeded": false,
      "isDisabled": false,
      "isUnlimited": false,
      "usagePercentage": 5
    },
    "attributeQuota": {
      "featureType": "attribute",
      "unit": "count",
      "limit": 0,
      "used": 0,
      "remaining": 0,
      "isExceeded": false,
      "isDisabled": true,
      "isUnlimited": false,
      "usagePercentage": 0
    },
    "vlmQuota": {
      "featureType": "vlm",
      "unit": "tokens",
      "limit": 0,
      "used": 0,
      "remaining": 0,
      "isExceeded": false,
      "isDisabled": true,
      "isUnlimited": false,
      "usagePercentage": 0
    }
  }
}

功能配額欄位（FeatureQuotaStatus）

欄位	說明
`featureType`	功能類型 (`alert` / `attribute` / `vlm`)
`unit`	計量單位 (`seconds` / `count` / `tokens`)
`limit`	配額上限（0 = 禁用，-1 = 無上限）
`used`	已使用數量
`remaining`	剩餘可用數量
`isExceeded`	是否超限
`isDisabled`	是否禁用（`limit = 0`）
`isUnlimited`	是否無上限（`limit = -1`）
`usagePercentage`	使用百分比

更新配額限制

PATCH /api/v1/devices/{id}/quota

參數	型別	說明
`quotaSeconds`	Number 或 null	設備配額（秒），null = 無上限