REST API

觀眾端 API

概述

注意：Viewer API 不需要 API Key 認證。透過 URL 中的 {token}（4 字元短碼 a-z0-9 的廣播分享 Token）識別廣播。

GET /api/v1/viewer/broadcasts/{token}

功能說明

取得指定廣播的公開資訊，供觀眾端顯示頻道資訊。此端點只回傳公開資訊，不包含敏感資料。

認證方式

無需 API Key 認證，透過 URL 路徑中的 {token} 識別廣播。

請求參數

參數	類型	位置	必填	說明
`token`	string	path	是	廣播分享 Token（4 字元短碼，字符集 a-z0-9）

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/viewer/broadcasts/a3f9"

成功回應

HTTP 200

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "我的廣播頻道",
    "access_type": "password",
    "requires_password": true,
    "status": "active",
    "is_live": true,
    "transcription_language": "zh-TW",
    "transcription_languages": ["zh-TW", "en-US"],
    "translation_languages": ["en-US", "ja-JP"],
    "tts_languages": ["en-US", "ja-JP"],
    "tts_voices": {
      "en-US": [
        { "voice_name": "en-US-JennyNeural", "display_name": "Jenny", "gender": "Female" },
        { "voice_name": "en-US-GuyNeural", "display_name": "Guy", "gender": "Male" }
      ],
      "ja-JP": [
        { "voice_name": "ja-JP-NanamiNeural", "display_name": "七海", "gender": "Female" },
        { "voice_name": "ja-JP-KeitaNeural", "display_name": "圭太", "gender": "Male" }
      ]
    }
  }
}

回應欄位說明

欄位	類型	說明
`id`	string	廣播 ID（UUID）
`name`	string	頻道名稱
`access_type`	string	存取類型：`public` / `password`
`requires_password`	boolean	是否需要密碼驗證
`status`	string	廣播狀態
`is_live`	boolean	是否正在直播
`transcription_language`	string	轉錄語言（向後相容，等於 `transcription_languages` 首元素）
`transcription_languages`	array	轉錄語言列表（`string[]`，最多 10 個、不可重複）
`translation_languages`	array	翻譯語言列表
`tts_languages`	array	主講方已啟用語音播報的語言；頻道未在直播中時為空陣列
`tts_voices`	object	各翻譯語言的 TTS 語音列表（減少觀眾端額外 API 呼叫）

tts_voices 結構說明

tts_voices 是一個以語言代碼為 key 的物件，每個語言包含可用語音陣列：

欄位	類型	說明
`voice_name`	string	語音名稱（API 用）
`display_name`	string	顯示名稱
`gender`	string	性別：`Female` / `Male`

特有錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`broadcast_token_invalid`	401	Token 無效或不存在	確認 Token 正確
`broadcast_token_revoked`	401	廣播已被撤銷	該廣播已不可使用
`too_many_requests`	429	請求過於頻繁，詳見頻率限制	依回應標頭 `Retry-After` 的秒數等待後再試

POST /api/v1/viewer/broadcasts/{token}/verify

功能說明

驗證觀眾密碼並取得觀眾存取 Token。取得的 viewer_access_token 用於連線 SSE 即時字幕串流。

若該頻道為公開頻道（不需密碼），仍可呼叫此端點，將直接回傳成功且 viewer_access_token 為 null。

認證方式

無需 API Key 認證，透過 URL 路徑中的 {token} 識別廣播。

請求參數

參數	類型	位置	必填	說明
`token`	string	path	是	廣播分享 Token（4 字元短碼，字符集 a-z0-9）
`password`	string	body	是	頻道密碼（最多 12 字元；驗證實際密碼是否正確由建立時設定決定）

請求範例

curl -X POST "https://vas-poc.vurbo.ai/api/v1/viewer/broadcasts/a3f9/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "mySecret123"
  }'

成功回應

HTTP 200 -- 密碼正確

{
  "data": {
    "viewer_access_token": "aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vWaB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW",
    "expires_at": "2026-02-24T10:00:00.000Z"
  }
}

HTTP 200 -- 公開頻道（不需密碼）

{
  "data": {
    "viewer_access_token": null,
    "message": "此頻道為公開，不需要密碼驗證"
  }
}

回應欄位說明

欄位	類型	說明
`viewer_access_token`	string	觀眾存取 Token（24 小時有效），公開頻道為 `null`
`expires_at`	string	Token 過期時間（ISO 8601 格式）

使用方式

取得 viewer_access_token 後，連線 SSE 即時字幕串流時需帶入：

GET /broadcast/{token}/text?viewer_access_token=xxx

特有錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`broadcast_token_invalid`	401	Token 無效	確認 Token 正確
`broadcast_token_revoked`	401	廣播已被撤銷	該廣播已不可使用
`broadcast_password_incorrect`	401	密碼錯誤	重新輸入正確密碼
`validation_failed`	422	參數驗證失敗	確認密碼格式正確
`too_many_requests`	429	請求過於頻繁，或密碼錯誤次數過多而暫時鎖定，詳見頻率限制	依回應標頭 `Retry-After` 的秒數等待後再試；鎖定期間即使密碼正確也要等待

頻率限制

兩個觀眾端點超過限制時都回 HTTP 429 too_many_requests，並帶 Retry-After 標頭（需要等待的秒數）。

限制	適用端點	規則
頻道總量	觀眾頁、密碼驗證（兩者分開計算）	同一頻道每分鐘的上限約為頻道最大觀眾數（`max_viewers`，見廣播 API）的 2 倍，最少 200 次；同一頻道的所有觀眾共用這個額度
查詢不存在的頻道	觀眾頁、密碼驗證（兩者合併計算）	同一來源 1 分鐘內查詢不存在的頻道（回 `broadcast_token_invalid`）達 20 次後，這個來源的觀眾頁與密碼驗證都會暫時回 429
密碼錯誤鎖定（依來源）	密碼驗證	同一頻道、同一來源 5 分鐘內密碼錯誤 30 次後暫時鎖定
密碼錯誤鎖定（依頻道）	密碼驗證	同一頻道 5 分鐘內累計密碼錯誤 100 次（不分來源）後暫時鎖定，這段期間這個頻道所有觀眾的密碼驗證都會回 429

鎖定期間，即使輸入正確密碼也會回 429，請依 Retry-After 等待後再試。
密碼正確不計入錯誤次數。
密碼錯誤鎖定只影響密碼驗證：觀眾頁照常可用，已取得的 viewer_access_token 在有效期內也照常可用。

從瀏覽器呼叫

觀眾頁可以放在您自己的網域。兩個觀眾端點都可從任何網域的網頁直接呼叫，不需要事先登記網域。

方法：GET、POST。請求標頭不限，例如 Content-Type: application/json。
請求不要帶憑證，例如 fetch 的 credentials: 'include' 或 XMLHttpRequest 的 withCredentials = true，否則瀏覽器會擋下回應。
收到 429 時，網頁可以讀取 Retry-After 標頭。
字幕串流 GET /broadcast/{token}/text 同樣可從任何網域連線。密碼保護的廣播請把 viewer_access_token 放在網址參數，不要放在請求標頭，用瀏覽器原生的 EventSource 即可。詳見廣播觀眾 SSE。

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

TTS API

Ad-hoc 摘要 SSE