REST API

廣播 API

GET /api/v1/broadcasts（廣播列表）

功能說明

查詢當前 API Key 擁有者的廣播列表（不包含已撤銷的頻道），支援分頁。

認證方式

Header：X-API-Key（詳見認證機制）

請求參數

參數	類型	必填	說明
`per_page`	integer	否	每頁筆數（預設 20）
`page`	integer	否	頁碼（預設 1）

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/broadcasts?per_page=10&page=1" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應（HTTP 200）

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "token": "a3f9",
      "name": "我的廣播頻道",
      "share_url": "https://vas-poc.vurbo.ai/broadcast/a3f9",
      "transcription_language": "zh-TW",
      "transcription_languages": ["zh-TW", "en-US"],
      "translation_languages": ["en-US", "ja-JP"],
      "tts_config": null,
      "speaker_diarization": false,
      "summary_template": null,
      "summary_language": null,
      "max_viewers": 100,
      "access_type": "public",
      "pass_code": null,
      "status": "pending",
      "is_live": false,
      "session_id": null,
      "current_recording_id": null,
      "recordings_count": 0,
      "peak_viewers": 0,
      "total_viewers": 0,
      "duration_ms": 0,
      "duration_formatted": "0:00",
      "started_at": null,
      "ended_at": null,
      "revoked_at": null,
      "created_at": "2026-01-03T10:00:00.000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 10,
    "total": 50
  }
}

回應欄位說明請參考建立廣播的回應欄位表。

特有錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`auth_missing_api_key`	401	API Key 未提供	確認 Header 包含 API Key
`auth_invalid_api_key`	401	API Key 無效	確認 API Key 正確

POST /api/v1/broadcasts（建立廣播）

功能說明

建立一個新的廣播 session，用於即時字幕串流。建立後會產生一個分享連結（含 4 字元短碼 Token，字符集 a-z0-9），觀眾可透過此連結接收即時字幕和翻譯。

認證方式

Header：X-API-Key（詳見認證機制）

請求參數

參數	類型	必填	說明
`transcription_languages`	string[]	是（或改用已棄用的 `transcription_language`）	轉錄語言代碼陣列（如 `["zh-TW", "en-US"]`，最多 10 種、不可重複）。啟用 `speaker_diarization` 時僅支援單一語言
`transcription_language`	string	否	（已棄用，向後相容）等同 `transcription_languages` 首元素（如 `zh-TW`）
`translation_languages`	string[]	否	翻譯語言代碼陣列（如 `["en-US", "ja-JP"]`，最多 12 種、不可重複）
`name`	string	否	頻道名稱（最大 100 字元，建立後無法修改；不會沿用為錄音名稱）
`access_type`	string	否	存取類型：`public`（預設）或 `password`
`pass_code`	string	條件	密碼（當 `access_type` 為 `password` 時必填，4-12 字元，限英文字母、數字與常見標點（不接受中文與空白））
`max_viewers`	integer	否	最大觀眾人數（1 ~ 帳戶觀眾上限；未指定時預設為該上限）
`speaker_diarization`	boolean	否	講者分離（預設 `false`）。啟用時僅支援單一轉錄語言，若同時提供多個轉錄語言會回 422
`tts_config`	object	否	TTS 預設設定（key 為語言代碼）
`tts_config.*.voice`	string	否	TTS 語音名稱（不指定使用預設語音）
`summary_template`	string	否	摘要模板 slug（最大 50 字元；需為已啟用的 `summary` 類別模板，可透過摘要模板 API 查詢）
`summary_language`	string	否	摘要輸出語言，須為支援語言清單中的語言代碼（不指定時預設使用第一個轉錄語言，即 `transcription_languages` 首元素）
`callback_url`	string	否	Webhook 回呼 URL（廣播錄音處理完成/失敗時通知，最大 2048 字元）

Webhook 通知：設定 callback_url 後，廣播錄音處理完成時會收到 recording.completed 事件，失敗時會收到 recording.failed 事件。詳見 Webhook 指南。

請求範例

curl -X POST "https://vas-poc.vurbo.ai/api/v1/broadcasts" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "transcription_languages": ["zh-TW", "en-US"],
    "translation_languages": ["en-US", "ja-JP"],
    "name": "我的廣播頻道",
    "access_type": "public",
    "max_viewers": 50,
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    },
    "summary_template": "meeting",
    "summary_language": "zh-TW",
    "callback_url": "https://your-server.com/webhooks/vas"
  }'

成功回應（HTTP 201）

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "token": "a3f9",
    "name": "我的廣播頻道",
    "share_url": "https://vas-poc.vurbo.ai/broadcast/a3f9",
    "transcription_language": "zh-TW",
    "transcription_languages": ["zh-TW", "en-US"],
    "translation_languages": ["en-US", "ja-JP"],
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    },
    "speaker_diarization": false,
    "summary_template": "meeting",
    "summary_language": "zh-TW",
    "max_viewers": 50,
    "access_type": "public",
    "pass_code": null,
    "status": "pending",
    "is_live": false,
    "session_id": null,
    "current_recording_id": null,
    "recordings_count": 0,
    "peak_viewers": 0,
    "total_viewers": 0,
    "duration_ms": 0,
    "duration_formatted": "0:00",
    "started_at": null,
    "ended_at": null,
    "revoked_at": null,
    "created_at": "2026-01-03T10:00:00.000Z"
  }
}

回應欄位說明

欄位	類型	說明
`id`	string	廣播 ID（UUID）
`token`	string	分享 Token（4 字元短碼，字符集 a-z0-9）
`name`	string	廣播名稱
`share_url`	string	預設分享網址（不是可開啟的觀眾頁面，見廣播指南）
`transcription_language`	string	轉錄語言（向後相容，等於 `transcription_languages` 首元素）
`transcription_languages`	string[]	轉錄語言列表
`translation_languages`	array	翻譯語言列表
`tts_config`	object	TTS 預設設定（key 為語言代碼）
`speaker_diarization`	boolean	講者分離開關
`summary_template`	string	摘要模板 slug（`null` 表示未設定）
`summary_language`	string	摘要輸出語言（`null` 時預設使用第一個轉錄語言，即 `transcription_languages` 首元素）
`max_viewers`	integer	最大觀眾人數
`access_type`	string	存取類型：`public` 或 `password`
`pass_code`	string	密碼明文（`access_type` 為 `password` 時有值，否則為 `null`）
`status`	string	狀態（見下方說明）
`is_live`	boolean	是否正在直播（`active` 或 `paused` 狀態時為 `true`）
`session_id`	string	WebSocket Session ID
`current_recording_id`	string	當前錄音 UUID：直播中才有值，為這一次開播的錄音（接管後為新的錄音）；預備階段或未在直播時為 `null`
`recordings_count`	integer	歷史錄音數量
`peak_viewers`	integer	歷史最高觀眾人數
`total_viewers`	integer	累計觀眾人數
`duration_ms`	integer	廣播時長（毫秒）
`duration_formatted`	string	格式化時長（分:秒）
`started_at`	string	開始時間（ISO 8601）
`ended_at`	string	結束時間（ISO 8601）
`revoked_at`	string	撤銷時間（ISO 8601）
`created_at`	string	建立時間（ISO 8601）

廣播狀態說明

狀態	說明
`pending`	已建立，尚未開始
`active`	進行中
`paused`	暫停中
`ended`	已結束
`revoked`	已撤銷

特有錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`validation_failed`	422	參數驗證失敗	確認參數格式正確
`plan_feature_not_allowed`	403	吃到飽方案不含廣播（廣播一律不含在方案內，v1.9.0）	廣播照點數計費；請改用點數制的 API Key

語言相關違規的錯誤碼：翻譯語言超過 12 種、轉錄語言超過 10 種、語言重複、必填空陣列、或「語者分離＋多語轉錄」等，REST 建立／更新一律由表單驗證層回 validation_failed（HTTP 422）。相同違規在 WebSocket start 路徑則回 too_many_languages 或 diarization_multilang_conflict（HTTP 400，見 error-codes.md）。差異來自兩條路徑的驗證時機不同：REST 在請求進入時先整批驗證，WebSocket 則在場次啟動時驗證。

GET /api/v1/broadcasts/{id}（查詢廣播狀態）

功能說明

查詢指定廣播的詳細資訊和目前狀態。

認證方式

Header：X-API-Key（詳見認證機制）

請求參數

參數	類型	必填	說明
`id`	string	是	廣播 ID（UUID，路徑參數）

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/broadcasts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應（HTTP 200）

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "token": "a3f9",
    "name": "我的廣播頻道",
    "share_url": "https://vas-poc.vurbo.ai/broadcast/a3f9",
    "transcription_language": "zh-TW",
    "transcription_languages": ["zh-TW", "en-US"],
    "translation_languages": ["en-US", "ja-JP"],
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    },
    "speaker_diarization": true,
    "summary_template": "meeting",
    "summary_language": "zh-TW",
    "max_viewers": 100,
    "access_type": "public",
    "pass_code": null,
    "status": "active",
    "is_live": true,
    "session_id": "ws_session_xyz",
    "current_recording_id": "660e8400-e29b-41d4-a716-446655440001",
    "recordings_count": 1,
    "peak_viewers": 25,
    "total_viewers": 30,
    "duration_ms": 1800000,
    "duration_formatted": "30:00",
    "started_at": "2026-01-03T10:00:00.000Z",
    "ended_at": null,
    "revoked_at": null,
    "created_at": "2026-01-03T09:55:00.000Z"
  }
}

回應欄位說明請參考建立廣播的回應欄位表。

特有錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`broadcast_session_not_found`	404	找不到指定廣播	確認廣播 ID 正確

PATCH /api/v1/broadcasts/{id}（更新廣播設定）

功能說明

更新廣播頻道的預設設定。此 API 可在廣播進行中（active 或 paused 狀態）呼叫，設定會立即儲存。

注意，廣播設定分為兩層，請依需求選擇對應介面
廣播是「頻道」概念——一個頻道可以多次開播（結束後回到 pending，可再次開播）。因此設定分為兩層：
層次改的是什麼用哪個介面
頻道預設值 之後每一次開播時的起始設定 本 API（PATCH）
進行中的這一場 當場實際採用的設定主講端 WebSocket action
本 API 更新的是頻道預設值，因此 transcription_languages、translation_languages、speaker_diarization、tts_config、summary_template、summary_language 於下一次開播時才生效，不會改變進行中該場的辨識、翻譯、語音合成與收尾摘要。這使得主辦方可以在直播進行中，先為下一場預先調整設定。
例外：access_type、pass_code、max_viewers 屬觀眾存取控制，會一併即時套用到進行中的直播。
若要更換當場的摘要設定並讓該場的收尾摘要採用新設定，請改用主講端 WebSocket 的 set_summary。

層次	改的是什麼	用哪個介面
頻道預設值	之後每一次開播時的起始設定	本 API（`PATCH`）
進行中的這一場	當場實際採用的設定	主講端 WebSocket action

認證方式

Header：X-API-Key（詳見認證機制）

請求參數

參數	類型	必填	說明
`id`	string	是	廣播 ID（UUID，路徑參數）
`transcription_languages`	string[]	否	僅下一場生效。轉錄語言代碼陣列（如 `["zh-TW", "en-US"]`，最多 10 種、不可重複）。啟用 `speaker_diarization` 時僅支援單一語言
`transcription_language`	string	否	僅下一場生效。（已棄用，向後相容）等同 `transcription_languages` 首元素（如 `zh-TW`）
`translation_languages`	string[]	否	僅下一場生效。翻譯語言代碼陣列（如 `["en-US", "ja-JP"]`，最多 12 種、不可重複）
`max_viewers`	integer	否	最大觀眾人數（1 ~ 帳戶觀眾上限）
`access_type`	string	否	存取類型：`public` 或 `password`
`pass_code`	string	條件	密碼（4-12 字元，限英文字母、數字與常見標點（不接受中文與空白），當 `access_type` 為 `password` 時必填）
`tts_config`	object	否	僅下一場生效。TTS 預設設定（會覆蓋現有設定，`null` 表示清除）
`speaker_diarization`	boolean	否	僅下一場生效。講者分離開關。啟用時僅支援單一轉錄語言，若同時提供多個轉錄語言會回 422
`summary_template`	string	否	僅下一場生效。摘要模板 slug（最大 50 字元，空字串 `""` 表示清除）。直播中要換摘要請用 WebSocket `set_summary`
`summary_language`	string	否	僅下一場生效。摘要輸出語言，須為支援語言清單中的語言代碼（空字串 `""` 表示清除）

注意：未提供任何可更新欄位時回 200 且資料不變。頻道名稱建立後無法修改，帶 name 會被忽略。summary_template 和 summary_language 傳入空字串 "" 表示清除設定；tts_config 傳入 null 表示清除設定；不傳表示不變更。

請求範例

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/broadcasts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "translation_languages": ["en-US", "ja-JP", "ko-KR"],
    "max_viewers": 200
  }'

成功回應（HTTP 200）

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "token": "a3f9",
    "name": "技術分享會直播",
    "share_url": "https://vas-poc.vurbo.ai/broadcast/a3f9",
    "transcription_language": "zh-TW",
    "transcription_languages": ["zh-TW", "en-US"],
    "translation_languages": ["en-US", "ja-JP", "ko-KR"],
    "tts_config": {
      "en-US": {"voice": "en-US-JennyNeural"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    },
    "speaker_diarization": true,
    "summary_template": "meeting",
    "summary_language": "zh-TW",
    "max_viewers": 200,
    "access_type": "public",
    "pass_code": null,
    "status": "active",
    "is_live": true,
    "session_id": "ws_session_xyz",
    "current_recording_id": "660e8400-e29b-41d4-a716-446655440001",
    "recordings_count": 1,
    "peak_viewers": 25,
    "total_viewers": 30,
    "duration_ms": 1800000,
    "duration_formatted": "30:00",
    "started_at": "2026-01-03T10:00:00.000Z",
    "ended_at": null,
    "revoked_at": null,
    "created_at": "2026-01-03T09:55:00.000Z"
  }
}

回應欄位說明請參考建立廣播的回應欄位表。

特有錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`broadcast_session_not_found`	404	找不到指定廣播	確認廣播 ID 正確
`validation_failed`	422	參數驗證失敗	確認參數格式正確

DELETE /api/v1/broadcasts/{id}（撤銷廣播）

功能說明

撤銷尚未開始的廣播。只有 pending 狀態的廣播可以撤銷，撤銷後 status 會變為 revoked。

認證方式

Header：X-API-Key（詳見認證機制）

請求參數

參數	類型	必填	說明
`id`	string	是	廣播 ID（UUID，路徑參數）

請求範例

curl -X DELETE "https://vas-poc.vurbo.ai/api/v1/broadcasts/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應（HTTP 200）

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "token": "a3f9",
    "name": "我的廣播頻道",
    "share_url": "https://vas-poc.vurbo.ai/broadcast/a3f9",
    "transcription_language": "zh-TW",
    "transcription_languages": ["zh-TW", "en-US"],
    "translation_languages": ["en-US", "ja-JP"],
    "tts_config": null,
    "speaker_diarization": false,
    "summary_template": null,
    "summary_language": null,
    "max_viewers": 100,
    "access_type": "public",
    "pass_code": null,
    "status": "revoked",
    "is_live": false,
    "session_id": null,
    "current_recording_id": null,
    "recordings_count": 0,
    "peak_viewers": 0,
    "total_viewers": 0,
    "duration_ms": 0,
    "duration_formatted": "0:00",
    "started_at": null,
    "ended_at": null,
    "revoked_at": "2026-01-03T10:05:00.000Z",
    "created_at": "2026-01-03T10:00:00.000Z"
  }
}

回應欄位說明請參考建立廣播的回應欄位表。

特有錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`broadcast_session_not_found`	404	找不到指定廣播	確認廣播 ID 正確
`broadcast_cannot_revoke`	422	只有 pending 狀態可以撤銷	檢查廣播目前狀態

DELETE /api/v1/broadcasts/batch（批次撤銷廣播）

功能說明

批次撤銷多個廣播。僅 pending 狀態的廣播會被撤銷，其他狀態的 ID 會被忽略。單次請求最多可操作 100 筆。

認證方式

Header：X-API-Key（詳見認證機制）

請求參數

參數	位置	類型	必填	說明
`ids`	body	array	是	廣播 ID 陣列（每個元素為 UUID，最多 100 筆）

請求範例

curl -X DELETE "https://vas-poc.vurbo.ai/api/v1/broadcasts/batch" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    ]
  }'

成功回應

HTTP 200

{
  "data": {
    "affected_count": 2
  }
}

回應欄位說明

欄位	類型	說明
`data.affected_count`	number	實際被撤銷的廣播數量（僅計入 pending 狀態）

特有錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`validation_failed`	422	參數驗證失敗	確認 `ids` 為 UUID 陣列且不超過 100 筆

版本：V1.24.1 最後更新：2026-10-07

認證票證 API

逐字稿條目 API