Viewer REST API

Overview

Note: The Viewer API does not require API Key authentication. Broadcasts are identified by the {token} in the URL (a 4-character short code, character set a-z0-9, used as the broadcast share token).

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

Description

Retrieve the public information of a specific broadcast for display on the viewer side. This endpoint returns only public information and does not include sensitive data.

Authentication

No API Key authentication is required. The broadcast is identified by the {token} in the URL path.

Request Parameters

Request Example

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

Success Response

HTTP 200

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Broadcast Channel",
    "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": "Nanami", "gender": "Female" },
        { "voice_name": "ja-JP-KeitaNeural", "display_name": "Keita", "gender": "Male" }
      ]
    }
  }
}

Response Fields

tts_voices Structure

tts_voices is an object keyed by language code, where each language contains an array of available voices:

Specific Error Codes

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

Description

Verify the viewer password and obtain a viewer access token. The returned viewer_access_token is used to connect to the SSE real-time subtitle stream.

If the channel is public (no password required), you can still call this endpoint; it will return success directly with viewer_access_token set to null.

Authentication

No API Key authentication is required. The broadcast is identified by the {token} in the URL path.

Request Parameters

Request Example

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

Success Response

HTTP 200 -- Password Correct

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

HTTP 200 -- Public Channel (No Password Required)

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

The message text is returned in Traditional Chinese and is meant for display only -- do not parse or match on it.

Response Fields

Usage

After obtaining the viewer_access_token, include it when connecting to the SSE real-time subtitle stream:

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

Specific Error Codes

Rate Limits

When a limit is exceeded, both viewer endpoints return HTTP 429 too_many_requests with a Retry-After header (the number of seconds to wait).

• While locked, even the correct password returns 429; wait for the period given in Retry-After, then retry.
• Correct passwords do not count toward the incorrect-password limits.
• The incorrect-password lock affects only password verification: the viewer page remains available, and a viewer_access_token already obtained remains usable until it expires.

Calling from a Browser

Your viewer page can live on your own domain. Both viewer endpoints can be called directly from a web page on any domain; there is no need to register your domain in advance.

• Methods: GET and POST. Request headers are not restricted, e.g. Content-Type: application/json.
• Do not send credentials, such as credentials: 'include' in fetch or withCredentials = true in XMLHttpRequest; otherwise the browser blocks the response.
• When a 429 is returned, the web page can read the Retry-After header.
• The caption stream GET /broadcast/{token}/text also accepts connections from any domain. For a password-protected broadcast, put viewer_access_token in the URL query parameter, not in a request header; the browser's native EventSource is all you need. See Broadcast Viewer SSE.

Version: V1.24.1 Last Updated: 2026-10-07