開始使用

Authentication

API Key

格式

Vurbo.ai API Key 格式為 vas_ + 32 位隨機字串：

vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW

取得方式

登入 Vurbo.ai Dashboard：https://vas-poc.vurbo.ai/dashboard
前往「API Keys」頁面
點擊「建立新 Key」
複製並妥善保存 API Key

注意：API Key 只會顯示一次，請務必保存好。

認證方式總覽

VAS API 根據不同的 API 類型使用不同的認證方式：

API 類型	認證方式	說明
REST API	`X-API-Key` Header	直接使用 API Key
SSE API	`X-API-Key` Header 或 `?api_key=` Query	支援兩種方式
WebSocket	Ticket 機制	以 API Key 換取一次性 Ticket
觀眾端 API	Token / 無認證	透過分享 Token 識別

方式一：X-API-Key Header

適用於 REST API 和 SSE API。

將 API Key 放入 HTTP Header：

X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW

REST API 範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

SSE API 範例

SSE API 支援兩種認證方式：

方式 A：Header（需使用 fetch API，瀏覽器原生 EventSource 不支援自訂 Header）：

const response = await fetch(
  'https://vas-poc.vurbo.ai/api/v1/sse/history/transcribe/{taskId}',
  {
    headers: { 'X-API-Key': 'vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW' }
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  // 解析 SSE 事件...
}

方式 B：Query Parameter（可搭配瀏覽器原生 EventSource 使用）：

const eventSource = new EventSource(
  'https://vas-poc.vurbo.ai/api/v1/sse/history/transcribe/{taskId}?api_key=vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW'
);

eventSource.addEventListener('init_metadata', (e) => {
  const data = JSON.parse(e.data);
  console.log(data);
});

注意：Query Parameter 方式會將 API Key 暴露在 URL 中，建議僅在無法使用 Header 的場景（如瀏覽器原生 EventSource）使用。

方式二：Ticket 機制（WebSocket 專用）

WebSocket 連線使用 Ticket 機制進行認證，避免在連線 URL 中暴露 API Key。

流程

1. REST API 換取 Ticket  →  POST /api/v1/auth/ticket（使用 X-API-Key）
2. 使用 Ticket 連線      →  WebSocket Sec-WebSocket-Protocol: ticket.{TICKET}

步驟 1：取得 Ticket

curl -X POST "https://vas-poc.vurbo.ai/api/v1/auth/ticket" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

回應：

{
  "ticket": "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "expires_in": 60
}

欄位	類型	說明
`ticket`	string	一次性 Ticket（32 字元）
`expires_in`	int	有效期（秒）

步驟 2：使用 Ticket 連線 WebSocket

將 Ticket 放入 Sec-WebSocket-Protocol，格式為 ticket.{TICKET_VALUE}：

const ws = new WebSocket('wss://vas-poc.vurbo.ai/ws', [`ticket.${ticket}`]);

ws.onopen = () => {
  console.log('Connected! Protocol:', ws.protocol);
};

Node.js 範例：

const WebSocket = require('ws');
const ws = new WebSocket('wss://vas-poc.vurbo.ai/ws', [`ticket.${ticket}`]);

Ticket 特性

特性	說明
有效期	60 秒
使用次數	僅能使用一次（使用後立即刪除）
安全性	API Key 不會暴露在 WebSocket 連線中

Ticket 錯誤碼

錯誤碼	說明
`ticket_invalid`	Ticket 無效或已過期
`ticket_expired`	Ticket 已過期
`ticket_already_used`	Ticket 已被使用
`ticket_validation_failed`	Ticket 驗證失敗

完整 API 規格請參考 Auth Ticket API。

方式三：Token 認證（觀眾端）

廣播觀眾端 API 不需要 API Key，透過廣播分享 Token 進行識別。

觀眾 SSE 連線

// 公開廣播
const eventSource = new EventSource(
  'https://vas-poc.vurbo.ai/broadcast/{token}/text'
);

// 密碼保護廣播（需先透過密碼驗證取得 viewer_access_token）
const eventSource = new EventSource(
  'https://vas-poc.vurbo.ai/broadcast/{token}/text?viewer_access_token={token}'
);

詳細說明請參考 Viewer API 和廣播觀眾 SSE。

認證錯誤

錯誤碼	HTTP	說明	處理建議
`auth_missing_api_key`	401	缺少 API Key	確認請求包含 `X-API-Key` Header
`auth_invalid_api_key`	401	API Key 無效	確認 API Key 正確
`auth_invalid_key_format`	401	API Key 格式錯誤	確認格式為 `vas_` 開頭 + 32 位字串
`auth_key_expired`	401	API Key 已過期	重新申請 API Key
`auth_key_disabled`	401	API Key 已停用	聯繫技術支援
`auth_user_disabled`	403	帳戶已停用	聯繫技術支援
`auth_budget_exceeded`	402	月度預算已超額	等待下月預算重置或調整預算

錯誤回應範例

{
  "type": "error",
  "data": {
    "error_code": "auth_invalid_api_key",
    "severity": "fatal",
    "message": "API Key 無效",
    "context": "auth",
    "request_id": "req_abc123xyz789",
    "timestamp": "2026-01-15T10:30:45.123Z"
  }
}

完整錯誤碼列表請參考錯誤碼參考。

預算與限制

項目	說明
月度預算	依方案設定 `monthly_budget_usd`，超額時回傳 HTTP 402
並行連線數	依方案而定

安全性建議

不要將 API Key 寫死在前端程式碼中
不要將 API Key 提交至版本控制系統
使用環境變數或密鑰管理服務儲存 API Key
定期輪換 API Key
WebSocket 連線請使用 Ticket 機制，避免在 URL 中暴露 API Key

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

概觀

Vurbo.ai API Service（VAS）的服務範圍與 API 構成。

Concepts