REST API
Broadcasts
目錄
- GET /api/v1/broadcasts（廣播列表）
- POST /api/v1/broadcasts（建立廣播）
- GET /api/v1/broadcasts/{id}（查詢廣播狀態）
- PATCH /api/v1/broadcasts/{id}（更新廣播設定）
- DELETE /api/v1/broadcasts/{id}（撤銷廣播）
- DELETE /api/v1/broadcasts/batch（批次撤銷廣播）
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",
"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": "00: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_language | string | 是 | 轉錄語言代碼（如 zh-TW） |
translation_languages | string | 否 | 翻譯語言代碼陣列 |
name | string | 否 | 頻道名稱（最大 100 字元） |
access_type | string | 否 | 存取類型：public（預設）或 password |
pass_code | string | 條件 | 密碼（當 access_type 為 password 時必填，4-12 字元） |
max_viewers | integer | 否 | 最大觀眾人數（預設為方案上限） |
speaker_diarization | boolean | 否 | 講者分離（預設 false） |
tts_config | object | 否 | TTS 預設設定（key 為語言代碼） |
tts_config.*.voice | string | 否 | TTS 語音名稱（不指定使用預設語音） |
tts_config.*.speaking_rate | number | 否 | TTS 語速（0.5 ~ 2.0，預設 1.0） |
summary_template | string | 否 | 摘要模板 slug（最大 50 字元；需為已啟用的 summary 類別模板，可透過 摘要模板 API 查詢） |
summary_language | string | 否 | 摘要輸出語言（不指定時預設使用 transcription_language） |
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_language": "zh-TW",
"translation_languages": ["en-US", "ja-JP"],
"name": "我的廣播頻道",
"access_type": "public",
"max_viewers": 50,
"tts_config": {
"en-US": {"voice": "en-US-JennyNeural", "speaking_rate": 1.0},
"ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
},
"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",
"translation_languages": ["en-US", "ja-JP"],
"tts_config": {
"en-US": {"voice": "en-US-JennyNeural", "speaking_rate": 1.0},
"ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
},
"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 | 轉錄語言 |
translation_languages | array | 翻譯語言列表 |
tts_config | object | TTS 預設設定（key 為語言代碼） |
speaker_diarization | boolean | 講者分離開關 |
summary_template | string | 摘要模板 slug（null 表示未設定） |
summary_language | string | 摘要輸出語言（null 時預設使用 transcription_language） |
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（直播中才有值） |
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 | 參數驗證失敗 | 確認參數格式正確 |
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",
"translation_languages": ["en-US", "ja-JP"],
"tts_config": {
"en-US": {"voice": "en-US-JennyNeural", "speaking_rate": 1.0},
"ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
},
"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 狀態）呼叫，即時調整設定。
認證方式
Header：X-API-Key（詳見 認證機制）
請求參數
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
id | string | 是 | 廣播 ID（UUID，路徑參數） |
transcription_language | string | 否 | 轉錄語言代碼（如 zh-TW） |
translation_languages | string | 否 | 翻譯語言代碼陣列 |
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 | 否 | 講者分離開關 |
summary_template | string | 否 | 摘要模板 slug（最大 50 字元，空字串 "" 表示清除） |
summary_language | string | 否 | 摘要輸出語言（空字串 "" 表示清除） |
注意：至少需要提供一個可更新欄位。
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",
"translation_languages": ["en-US", "ja-JP", "ko-KR"],
"tts_config": {
"en-US": {"voice": "en-US-JennyNeural", "speaking_rate": 1.0},
"ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
},
"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 正確 |
broadcast_cannot_update | 422 | 只有 pending/active/paused 可更新 | 檢查廣播目前狀態 |
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",
"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.5.7 最後更新：2026-05-20