REST API

Viewer

概述

注意：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",
    "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	轉錄語言
`translation_languages`	array	翻譯語言列表
`tts_languages`	array	支援 TTS 的語言（直播中從 Go 取得，否則從預設設定取得）
`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	廣播已被撤銷	該廣播已不可使用

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 小時有效，含 IP 綁定），公開頻道為 `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	參數驗證失敗	確認密碼格式正確

版本：V1.5.7 最後更新：2026-05-20

Tts

Audio