API 文件

REST API 總覽

注意：本文件中的網址（vas-poc.vurbo.ai）為預計部署網址，正式上線後將另行通知。

目錄
API 概述
- 認證方式
- API 分類
GET /api/v1/version（查詢部署版本）
GET /api/v1/me/plan（查詢我的方案）
GET /api/v1/me/credit-lots、/me/usage、/me/key（金鑰自助查詢）
GET /api/v1/tasks（取得任務列表）
- 功能說明
- 使用場景
- 認證方式
- 請求範例
- 成功回應
- 回應範例
- 錯誤回應
DELETE /api/v1/tasks/{taskId}（刪除任務）
- 功能說明
- 使用場景
- 認證方式
- 請求參數
- 請求範例
- 成功回應
- 錯誤回應
PUT /api/v1/tasks/batch/pin（批次更新釘選狀態）
DELETE /api/v1/tasks/batch（批次刪除任務）
PUT /api/v1/tasks/{taskId}/pin（更新釘選狀態）
- 功能說明
- 使用場景
- 認證方式
- 請求參數
- 請求範例
- 成功回應
- 錯誤回應
PUT /api/v1/tasks/{taskId}/read（標記已讀）
- 功能說明
- 使用場景
- 認證方式
- 請求參數
- 請求範例
- 成功回應
- 錯誤回應
PATCH /api/v1/tasks/{taskId}/name（更新任務名稱）
- 功能說明
- 使用場景
- 認證方式
- 請求參數
- 請求範例
- 成功回應
- 錯誤回應
GET /api/v1/tasks/{taskId}/audio/export（下載任務音檔）
GET /api/v1/tasks/{taskId}/transcript/export（下載逐字稿）
POST /api/v1/tasks/{taskId}/force-fail（強制標記為失敗）
POST /api/v1/tasks/{taskId}/retry（重新處理失敗任務）
音檔匯入 API
- POST /api/v1/imports/check-quota（檢查點數）
- POST /api/v1/imports（上傳音檔）
- GET /api/v1/imports/{importId}（查詢匯入狀態）
- GET /api/v1/imports（取得匯入列表）
Audio API
- GET /api/v1/sse/audio/{taskId}（音訊串流播放）
TTS API
- GET /api/v1/tts/voices（取得 TTS 語音列表）
Broadcasts API
- 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（批次撤銷廣播）
Viewer API
- GET /api/v1/viewer/broadcasts/{token}（取得廣播公開資訊）
- POST /api/v1/viewer/broadcasts/{token}/verify（密碼驗證）
Recording Speaker 編輯 API
- PATCH /api/v1/tasks/{taskId}/speakers/rename（全域重命名說話者）
- PATCH /api/v1/tasks/{taskId}/speakers/reassign（修改單句語者身份）
Summary Template API
- GET /api/v1/summary-templates（取得摘要模板列表）
字庫驗證 API
- POST /api/v1/glossary/validate（存檔前驗證字庫）
錯誤處理

API 概述

項目	值
基礎路徑	`https://vas-poc.vurbo.ai/api/v1`
協定	HTTPS
資料格式	JSON

認證方式

需認證的 API 透過 HTTP Header 傳送 API Key：

X-API-Key: vas_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API 分類

類別	路徑前綴	認證方式	用途
Tasks API	`/api/v1/tasks`	Header `X-API-Key`	任務管理、音檔／逐字稿匯出
Import API	`/api/v1/imports`	Header `X-API-Key`	音檔匯入
Audio API	`/api/v1/sse/audio`	Header `X-API-Key`	音訊檔案播放
TTS API	`/api/v1/tts`	Header `X-API-Key`	TTS 語音服務
Broadcasts API	`/api/v1/broadcasts`	Header `X-API-Key`	廣播管理
Viewer API	`/api/v1/viewer/broadcasts`	無	觀眾端公開資訊
Recording Speaker API	`/api/v1/tasks/{taskId}/speakers`	Header `X-API-Key`	逐字稿語者編輯（V1.4.1 起 `recordings` 路徑為 deprecated alias，V1.6.0 移除）
Summary Template API	`/api/v1/summary-templates`	Header `X-API-Key`	摘要模板查詢
Broadcast REST API	`/broadcast`	Token（路徑參數）	廣播即時狀態
Version API	`/api/v1/version`	無	部署版本查詢（上線前版本閘門用）
My Plan API	`/api/v1/me/plan`	Header `X-API-Key`	查詢目前計費制度、方案內容與用量（v1.9.0）
Key Self-Service API	`/api/v1/me/credit-lots`、`/api/v1/me/usage`、`/api/v1/me/key`	Header `X-API-Key`	查詢這把 API Key 的點數批次、用量紀錄與設定（V1.21.0）
字庫驗證 API	`/api/v1/glossary/validate`	Header `X-API-Key`	存檔前檢查字庫衝突（V1.14.0，由即時服務網域提供）

GET /api/v1/version（查詢部署版本）

功能說明

回報服務目前部署的版本，供串接方在上線前做版本閘門檢查——例如「某項修正需 ≥ vX.Y.Z 才可上線」。

免認證。版本閘門若因認證問題失敗，會與「版本不符」混淆而失去把關意義。

注意：即時服務與 REST 服務各自獨立發版，版本可能不同。 若要確認的修正屬即時錄音／廣播（WebSocket）範疇，請改查即時服務的 /version（見下方）。

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/version"

成功回應（HTTP 200）

{
  "service": "vas-api",
  "version": "1.7.7",
  "build": "a1b2c3d4e5f6"
}

回應欄位說明

欄位	類型	說明
`service`	string	服務識別：`vas-api`（REST）／`vas-realtime`（WebSocket）
`version`	string	平台版本號（對應本文件的版本，如 `1.7.7`）
`build`	string	建置識別碼，供追溯特定建置；同版本號可能有多次建置

即時服務（WebSocket）的版本查詢

即時服務提供對應端點，路徑為 /version。

主機請使用您建立 WebSocket 連線的同一個網域，將協定由 wss:// 換成 https:// 即可（各環境的即時服務與 REST 服務可能位於不同網域，請以貴方實際取得的連線設定為準）：

# 若 WebSocket 連線為 wss://<即時服務網域>/ws
curl -X GET "https://<即時服務網域>/version"

{
  "service": "vas-realtime",
  "version": "1.7.7",
  "build": "a1b2c3d4e5f6"
}

版本閘門建議做法

本端點自 V1.7.7 起提供。因此：

端點有回應 → 版本必定 ≥ V1.7.7，可直接比對 version 判斷。
端點回 404 → 版本早於 V1.7.7，無法由此端點判定確切版本，請洽服務窗口確認。

GET /api/v1/me/plan（查詢我的方案）

功能說明

查詢這把 API Key 目前的計費制度與方案內容（v1.9.0 新增）。被 plan_feature_not_allowed（HTTP 403）或 plan_daily_limit_reached（HTTP 402）等方案限制擋下時，可用此端點查「我的方案含什麼、離上限多遠、限制何時恢復」。

唯讀端點：點數用盡時也可查詢。

完整請求／回應規格（三種回應形狀的完整欄位表）見 reference/rest/me-plan.md。

請求範例

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

成功回應（HTTP 200）

回應形狀依計費制度而異：

吃到飽方案（mode: "unlimited"，綁定方案）：

{
  "data": {
    "mode": "unlimited",
    "plan": {
      "name": "專業方案",
      "expired_at": "2027-07-31T23:59:59+08:00"
    },
    "features": [
      { "slug": "stt", "name": "基礎語音轉錄", "included": true },
      { "slug": "diarization", "name": "語者分離", "included": true },
      { "slug": "broadcast", "name": "廣播", "included": false }
    ],
    "oneoff_features": [
      { "slug": "summary", "name": "AI 會議摘要", "included": true },
      { "slug": "import", "name": "檔案匯入", "included": false }
    ],
    "limits": {
      "daily_soft_limit_minutes": 480,
      "daily_hard_limit_minutes": 600,
      "max_concurrent_sessions": 2,
      "daily_used_minutes": 123,
      "max_transcription_languages": 4,
      "max_session_minutes": 240,
      "rolling_limit_minutes": 3000,
      "rolling_used_minutes": 850,
      "auth_total_limit_minutes": 60000,
      "auth_total_used_minutes": 12345,
      "restriction_recovery_at": null
    }
  }
}

點數制（mode: "credit"）：

{
  "data": {
    "mode": "credit",
    "plan": null,
    "available_credit": 480.5
  }
}

無方案限制的吃到飽授權（mode: "unlimited"，罕見）：

{
  "data": {
    "mode": "unlimited",
    "plan": null,
    "features": { "all": true },
    "expired_at": "2027-01-31T23:59:59+08:00"
  }
}

主要欄位：features[] 為每分鐘計費類功能（included 表方案是否包含；廣播恆為 false）、oneoff_features[] 為一次性功能（摘要、全文重翻、檔案匯入）、limits 為方案各項上限與目前用量（null 表示該項不限）。完整欄位說明見 reference/rest/me-plan.md。

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`auth_missing_api_key`	401	API Key 未提供	確認 Header 包含 API Key
`auth_invalid_api_key`	401	API Key 無效	確認 API Key 正確

GET /api/v1/me/credit-lots、/me/usage、/me/key（金鑰自助查詢）

端點	用途
`GET /api/v1/me/credit-lots`	扣點時會動用的點數批次（專屬額度與可用的帳戶點數），只列仍有剩餘且未過期的，先到期的排前面
`GET /api/v1/me/usage`	扣點紀錄，每場錄音／廣播、每次匯入／摘要／重翻各一列，新的排前面；支援 `page`、`per_page`（5～20，預設 20）
`GET /api/v1/me/key`	API Key 的名稱、到期日、每月點數上限與本月花費、併發上限、Webhook 網址、是否設定來源 IP 限制

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/me/usage?page=1&per_page=20" \
  -H "X-API-Key: YOUR_API_KEY"

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`validation_failed`	422	`/me/usage` 的 `page` 或 `per_page` 不合法	`page` ≥ 1、`per_page` 為 5～20 的整數
`auth_missing_api_key`	401	API Key 未提供	確認 Header 包含 API Key
`auth_invalid_api_key`	401	API Key 無效	確認 API Key 正確

GET /api/v1/tasks（取得任務列表）

功能說明

取得目前使用者的錄音任務列表。可透過 status 參數篩選不同處理階段的任務，或用 task_ids[] 只查指定的任務。

請求參數（Query）

參數	類型	必填	預設值	說明
`status`	string	否	`completed`	篩選任務狀態：`completed`、`active`、`all`
`task_ids[]`	string[]	否	—	只查這些任務（每個元素為 UUID，1～100 筆）

status 值	說明
`completed`	只回傳已完成的任務（預設，向後相容）
`active`	回傳進行中的任務（`recording`、`importing`、`uploading`、`processing`）
`all`	回傳所有任務，不過濾狀態

task_ids 篩選說明

只回傳清單內、屬於目前帳號的任務；不存在或不屬於目前帳號的 ID 會直接略過，不會回錯誤。
status 照樣套用：沒帶 status 時仍只回傳已完成的任務。要不論狀態查詢指定任務，請加 status=all。
回應格式與不帶 task_ids 時相同。
超過 100 筆、格式不是 UUID，或 task_ids 不是陣列（例如沒加 [] 的 task_ids=<UUID>），會回 422 validation_failed。

請求範例

# 預設查詢（已完成的任務）
curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

# 查詢進行中的任務
curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks?status=active" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

# 只查指定的任務（不論狀態，需加 status=all）
curl -G "https://vas-poc.vurbo.ai/api/v1/tasks" \
  --data-urlencode "task_ids[]=550e8400-e29b-41d4-a716-446655440000" \
  --data-urlencode "task_ids[]=6ba7b810-9dad-11d1-80b4-00c04fd430c8" \
  --data-urlencode "status=all" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應

欄位	類型	說明
`data.tasks`	array	任務列表
`data.tasks[].task_id`	string	任務 ID（UUID）
`data.tasks[].title`	string	任務標題
`data.tasks[].type`	string	錄音類型
`data.tasks[].type_source`	string	來源類型（realtime / import / broadcast）
`data.tasks[].duration_ms`	number	錄音時長（毫秒）
`data.tasks[].duration_formatted`	string	格式化時長（分:秒）
`data.tasks[].transcription_languages`	array	轉錄語言列表
`data.tasks[].translation_languages`	array	翻譯語言列表
`data.tasks[].created_at`	string	建立時間（ISO 8601）
`data.tasks[].processing_status`	string	處理狀態
`data.tasks[].is_pinned`	boolean	是否已釘選
`data.tasks[].is_unread`	boolean	是否未讀

processing_status 狀態值

狀態值	說明	適用場景
`recording`	錄音進行中	即時錄音、廣播
`importing`	音檔匯入處理中	音檔匯入
`uploading`	上傳至雲端中	錄音停止後上傳階段
`processing`	後處理中	摘要、翻譯等
`completed`	處理完成	所有場景
`failed`	處理失敗	所有場景

回應範例

{
  "data": {
    "tasks": [
      {
        "task_id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "會議記錄",
        "type": "transcribe",
        "type_source": "realtime",
        "duration_ms": 60000,
        "duration_formatted": "1:00",
        "transcription_languages": ["zh-TW"],
        "translation_languages": ["en-US"],
        "created_at": "2026-02-25T10:00:00Z",
        "processing_status": "completed",
        "is_pinned": false,
        "is_unread": true
      }
    ]
  }
}

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`auth_missing_api_key`	401	API Key 未提供	確認 Header 包含 API Key
`auth_invalid_api_key`	401	API Key 無效	確認 API Key 正確
`validation_failed`	422	參數驗證失敗	確認 `task_ids` 為 UUID 陣列且為 1～100 筆

DELETE /api/v1/tasks/{taskId}（刪除任務）

功能說明

刪除指定的任務。刪除是永久的，無法復原：任務連同其音檔、逐字稿、摘要、翻譯與匯入原檔會一併移除，之後查詢、匯出、重翻都無法再取得。

仍在處理中的任務不能刪除（processing_status 為 recording、importing、uploading、pending、processing，或該任務的匯入仍在處理中），會回 422 invalid_processing_status。請等它完成或失敗後再刪；若任務卡住不動，可先用 POST /api/v1/tasks/{taskId}/force-fail 標為失敗；但匯入仍在處理中的任務無法以此解除，需等匯入結束後再刪。

使用場景

清除不需要的錄音記錄
整理任務列表

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`taskId`	string	是	任務 ID（UUID）

請求範例

curl -X DELETE "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應

{
  "message": "任務已刪除"
}

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`recording_not_found`	404	找不到指定的錄音	確認 taskId 正確
`invalid_processing_status`	422	任務仍在處理中，不能刪除	等任務完成或失敗後再刪；卡住的錄音可先 `force-fail`，匯入仍在處理中則需等匯入結束

PUT /api/v1/tasks/batch/pin（批次更新釘選狀態）

功能說明

批次更新多個任務的釘選狀態。單次請求最多可操作 100 筆任務。僅會影響屬於當前用戶的任務，不屬於該用戶的 ID 會被忽略。

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	位置	類型	必填	說明
`task_ids`	body	array	是	任務 ID 陣列（每個元素為 UUID，最多 100 筆）
`is_pinned`	body	boolean	是	釘選狀態

請求範例

curl -X PUT "https://vas-poc.vurbo.ai/api/v1/tasks/batch/pin" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "task_ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    ],
    "is_pinned": true
  }'

成功回應

{
  "data": {
    "affected_count": 2
  }
}

回應欄位說明

欄位	類型	說明
`data.affected_count`	number	實際被更新的任務數量

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`validation_failed`	422	參數驗證失敗	確認 `task_ids` 為 UUID 陣列且不超過 100 筆，`is_pinned` 為布林值

DELETE /api/v1/tasks/batch（批次刪除任務）

功能說明

批次刪除多個任務。刪除是永久的，無法復原，範圍與單筆刪除相同。單次請求最多可操作 100 筆任務。僅會影響屬於當前用戶的任務，不屬於該用戶的 ID 會被忽略。

仍在處理中的任務會被跳過、不刪除，並列在回應的 skipped_task_ids；其餘任務照常刪除，整批不會因此失敗。

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	位置	類型	必填	說明
`task_ids`	body	array	是	任務 ID 陣列（每個元素為 UUID，最多 100 筆）

請求範例

curl -X DELETE "https://vas-poc.vurbo.ai/api/v1/tasks/batch" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "task_ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
    ]
  }'

成功回應

{
  "data": {
    "affected_count": 2,
    "skipped_task_ids": []
  }
}

回應欄位說明

欄位	類型	說明
`data.affected_count`	number	實際被刪除的任務數量
`data.skipped_task_ids`	string[]	因仍在處理中而未刪除的任務 ID。全部照請求刪除時為空陣列。不屬於當前用戶的 ID 不會出現在這裡

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`validation_failed`	422	參數驗證失敗	確認 `task_ids` 為 UUID 陣列且不超過 100 筆

PUT /api/v1/tasks/{taskId}/pin（更新釘選狀態）

功能說明

更新任務的釘選狀態。釘選的任務會在列表中優先顯示。

使用場景

標記重要的錄音
快速存取常用任務

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`taskId`	string	是	任務 ID（路徑參數）
`is_pinned`	boolean	是	釘選狀態

請求範例

curl -X PUT "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/pin" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{"is_pinned": true}'

成功回應

{
  "data": {
    "is_pinned": true
  }
}

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`recording_not_found`	404	找不到指定的錄音	確認 taskId 正確
`validation_failed`	422	參數驗證失敗	確認 is_pinned 為布林值

PUT /api/v1/tasks/{taskId}/read（標記已讀）

功能說明

將任務標記為已讀。

使用場景

標記已查看的錄音
清除未讀標記

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`taskId`	string	是	任務 ID（路徑參數）

請求範例

curl -X PUT "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/read" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應

{
  "data": {
    "is_unread": false
  }
}

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`recording_not_found`	404	找不到指定的錄音	確認 taskId 正確

PATCH /api/v1/tasks/{taskId}/name（更新任務名稱）

功能說明

更新指定任務的名稱。

使用場景

自訂錄音標題
修正自動生成的名稱

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`taskId`	string	是	任務 ID（路徑參數）
`name`	string	是	任務名稱（最大 60 字元）

請求範例

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/name" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{"name": "產品會議討論"}'

成功回應

{
  "message": "錄音名稱已更新",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "產品會議討論",
    "name_source": "user"
  }
}

欄位	類型	說明
`name_source`	string	名稱來源：`default`、`llm`、`user`

名稱來源說明：

name_source	說明	觸發條件
`user`	用戶明確設定的名稱	`set_name`、此 REST API（系統不會覆蓋）
`llm`	系統根據逐字稿自動生成	錄音結束時，若 name_source 非 `user`，系統自動生成
`default`	預設名稱	`start` 傳入的 `name`（初始預設，系統仍可覆蓋）或類型 + 流水號（如 `Transcription #1`）

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`recording_not_found`	404	找不到指定的錄音	確認 taskId 正確
`recording_unauthorized`	403	無權限操作此錄音	確認任務屬於該用戶
`validation_failed`	422	驗證失敗	確認 name 不為空且長度正確

GET /api/v1/tasks/{taskId}/audio/export（下載任務音檔）

功能說明

下載指定任務的原始錄音音檔。回應為二進位音訊流並附加 Content-Disposition: attachment 標頭，瀏覽器或下載工具會直接將內容儲存為檔案。檔名會優先使用錄音名稱（經清洗過的檔名），若名稱為空則退回 audio。

與音訊串流 API（GET /api/v1/sse/audio/{taskId}）的差異：
本端點：離線下載用途；回應附 Content-Disposition: attachment 標頭；不支援 Range Request。
音訊串流：播放用途；支援 HTTP Range Request 以便拖曳快進；回應不強制下載。

使用場景

離線保存錄音檔
批次匯出所有任務的原始音檔

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	位置	類型	必填	說明
`taskId`	path	string	是	任務 ID（UUID）

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/audio/export" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -OJ

提示：curl -OJ 會讓 curl 依伺服器回應的 Content-Disposition 自動命名儲存檔名。

成功回應

HTTP 200

HTTP/1.1 200 OK
Content-Type: audio/mp4
Content-Length: 1234567
Content-Disposition: attachment; filename="audio.m4a"; filename*=UTF-8''%E6%9C%83%E8%AD%B0%E8%A8%98%E9%8C%84.m4a
Cache-Control: no-cache

注意：所有錄音音檔一律以 M4A 容器（AAC 編碼）回傳，Content-Type 固定為 audio/mp4，副檔名為 .m4a。

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`recording_not_found`	404	找不到指定的錄音，或音檔在雲端儲存中不存在	確認 `taskId` 正確且錄音未被刪除
`recording_audio_not_ready`	422	音檔尚未上傳完成或處理中	稍後重試；可先透過 `GET /api/v1/tasks` 確認 `processing_status` 為 `completed`
`storage_download_failed`	500	儲存服務下載失敗	稍後重試；若持續失敗請聯絡支援

GET /api/v1/tasks/{taskId}/transcript/export（下載逐字稿）

功能說明

下載指定任務的逐字稿，支援五種格式：純文字、SubRip 字幕、YouTube SBV 字幕、WebVTT 字幕、CSV 試算表。回應內容包含原文與所有翻譯語言；回應附 Content-Disposition: attachment 標頭以供直接下載。檔名會優先使用錄音名稱（經清洗後的檔名），若名稱為空則退回 transcript，並統一加上 -transcript.{ext} 後綴。

與歷史逐字稿 SSE API（GET /api/v1/sse/history/transcribe/{taskId}）的差異：
本端點：離線下載用途；一次回傳完整檔案；可直接交給字幕軟體或試算表開啟。
SSE 歷史 API：漸進式載入用途；以 event stream 逐句推送原始結構資料（JSON 片段），供前端 UI 漸進渲染。

使用場景

下載逐字稿供字幕軟體使用（SRT / SBV / VTT）
匯出 CSV 供 Excel 或資料分析工具開啟
離線保存逐字稿純文字

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	位置	類型	必填	預設值	說明
`taskId`	path	string	是	—	任務 ID（UUID）
`format`	query	string	否	`txt`	格式：`txt` / `srt` / `sbv` / `vtt` / `csv`

format 格式說明

格式	時間格式	內容結構	典型用途
`txt`	—	每段一行 `[說話者] 原文`，翻譯以 4 個空白縮排為 `[語言碼] 譯文`	閱讀、紀錄保存
`srt`	`HH:MM:SS,mmm`	含序號，每段時間軸後原文與翻譯各占一行	SubRip 字幕（DaVinci Resolve、VLC 等）
`sbv`	`H:MM:SS.mmm`	無序號；時間軸以 `,` 分隔；原文與翻譯以 `\|` 串接為單行（換行符會被替換為空白）	YouTube 字幕上傳
`vtt`	`HH:MM:SS.mmm`	以 `WEBVTT` 作為表頭，每段時間軸後原文與翻譯各占一行	HTML5 `<track>` 字幕、Web 播放器
`csv`	`HH:MM:SS`（無毫秒）	UTF-8 BOM 開頭；欄位 `index,start,end,speaker,text,<每個翻譯語言一欄>`	Excel、資料分析

請求範例

# 預設 TXT 格式
curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/transcript/export" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -OJ

# 指定 SRT 格式
curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/transcript/export?format=srt" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -OJ

# CSV（Excel 可直接開啟，UTF-8 BOM 確保中文不亂碼）
curl -X GET "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/transcript/export?format=csv" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -OJ

成功回應

HTTP 200

HTTP/1.1 200 OK
Content-Type: text/csv; charset=UTF-8
Content-Length: 2048
Content-Disposition: attachment; filename="transcript.csv"; filename*=UTF-8''%E6%9C%83%E8%AD%B0%E8%A8%98%E9%8C%84-transcript.csv
Cache-Control: no-cache

注意：Content-Type 會依 format 參數動態決定：
格式 Content-Type
txt text/plain; charset=UTF-8
srt application/x-subrip
sbv text/plain; charset=UTF-8
vtt text/vtt; charset=UTF-8
csv text/csv; charset=UTF-8

格式	Content-Type
`txt`	`text/plain; charset=UTF-8`
`srt`	`application/x-subrip`
`sbv`	`text/plain; charset=UTF-8`
`vtt`	`text/vtt; charset=UTF-8`
`csv`	`text/csv; charset=UTF-8`

輸出範例

假設逐字稿包含兩段中文錄音（zh-TW）及兩種翻譯（en-US、ja-JP）：

TXT

[Alice] 你好，早安
    [en-US] Hello, good morning
    [ja-JP] おはよう
[Bob] 多謝
    [en-US] Thanks
    [ja-JP] ありがとう

SRT

1
00:00:00,500 --> 00:00:03,000
你好，早安
Hello, good morning
おはよう

2
00:00:03,000 --> 00:00:04,200
多謝
Thanks
ありがとう

SBV

0:00:00.500,0:00:03.000
你好，早安 | Hello, good morning | おはよう

0:00:03.000,0:00:04.200
多謝 | Thanks | ありがとう

VTT

WEBVTT

00:00:00.500 --> 00:00:03.000
你好，早安
Hello, good morning
おはよう

00:00:03.000 --> 00:00:04.200
多謝
Thanks
ありがとう

CSV（檔案開頭含 UTF-8 BOM EF BB BF）

index,start,end,speaker,text,en-US,ja-JP
1,00:00:00,00:00:03,Alice,你好，早安,"Hello, good morning",おはよう
2,00:00:03,00:00:04,Bob,多謝,Thanks,ありがとう

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`recording_not_found`	404	找不到指定的錄音	確認 `taskId` 正確且錄音未被刪除
`recording_transcript_not_ready`	422	逐字稿尚未產生完成或為空	先透過 `GET /api/v1/tasks` 確認 `processing_status = completed` 後再呼叫
`validation_failed`	422	參數驗證失敗	確認 `format` 為允許值之一（`txt` / `srt` / `sbv` / `vtt` / `csv`）
`storage_download_failed`	500	儲存服務下載失敗	稍後重試；若持續失敗請聯絡支援

POST /api/v1/tasks/{taskId}/force-fail（強制標記為失敗）

功能說明

將卡在非終態（recording / importing / uploading / pending / processing）的任務強制標記為失敗。操作成功後 processing_status 變為 failed、processing_error 寫入使用者提供的原因，並觸發 recording.failed webhook（payload.failure_source = user_forced）。已是終態（completed / failed）的任務會收到 422。

完整規格與前端範例請見：Tasks API — POST force-fail。

認證方式

Header：X-API-Key。

請求參數

參數	位置	類型	必填	說明
`taskId`	path	string	是	任務 ID（UUID）
`reason`	body	string \| null	否	失敗原因，最長 500 字元

請求範例

curl -X POST "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/force-fail" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{"reason": "錄音端斷線太久，放棄等待"}'

成功回應

HTTP 200

{
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "processing_status": "failed",
    "processing_error": "User-forced failure: 錄音端斷線太久，放棄等待 (previous status: recording)"
  }
}

錯誤回應

錯誤碼	HTTP	說明	處理建議
`recording_not_found`	404	找不到錄音或非本人錄音	確認 `taskId` 正確
`invalid_processing_status`	422	任務已是終態	已完成改用 `DELETE`；已失敗無需再次強制
`validation_failed`	422	`reason` 超過 500 字元或 `taskId` 格式錯誤	檢查 `reason` 長度與 UUID 格式

POST /api/v1/tasks/{taskId}/retry（重新處理失敗任務）

功能說明

將處於 failed 狀態的任務重新排入處理佇列。操作成功後 processing_status 變為 processing，processing_error 清空。重新排入會在狀態更新確實生效後才進行，不會讀到更新前的舊狀態。

前置條件：processing_status = failed 且 audio_status = success 且 transcript_status = success，任一不符回 422（details 會帶 audio_status / transcript_status 協助定位）。

完整規格請見：Tasks API — POST retry。

認證方式

Header：X-API-Key。

請求參數

參數	位置	類型	必填	說明
`taskId`	path	string	是	任務 ID（UUID）

請求範例

curl -X POST "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/retry" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應

HTTP 200

{
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "processing_status": "processing"
  }
}

錯誤回應

錯誤碼	HTTP	說明	details 欄位	處理建議
`recording_not_found`	404	找不到錄音或非本人錄音	—	確認 `taskId` 正確
`invalid_processing_status`	422	任務不在 `failed` 狀態	`current_status`	只有 `failed` 可 retry
`invalid_processing_status`	422	音檔 / 逐字稿未完整上傳	`current_status`、`audio_status`、`transcript_status`	確認來源完整；損毀請改用 `force-fail`
`task_already_processing`	409	同一筆任務仍有處理作業尚未結束	`task_id`	稍候再送出同一個請求，任務狀態未被改動

音檔匯入 API

音檔匯入 API 提供上傳音檔進行語音辨識與翻譯的功能。

POST /api/v1/imports/check-quota（檢查點數）

功能說明

檢查使用者點數是否足夠上傳指定時長的音檔。建議在上傳前先呼叫此 API 進行預檢查。

使用場景

上傳音檔前檢查點數是否足夠
顯示剩餘可用點數

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`duration_ms`	integer	是	音檔時長（毫秒，預設 1 秒 ~ 10 小時；實際上下限依部署設定，與上傳後的時長檢查同一組）

請求範例

curl -X POST "https://vas-poc.vurbo.ai/api/v1/imports/check-quota" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{"duration_ms": 3600000}'

成功回應

{
  "data": {
    "allowed": true,
    "reason": null,
    "is_unlimited": false,
    "remain_quota": 480.0,
    "duration_minutes": 60,
    "estimated_points": 60.0
  }
}

欄位	類型	說明
`allowed`	boolean	是否允許上傳（點數足夠或方案允許時為 true）
`reason`	string \| null	不允許的原因：`null`（通過）／`insufficient_credit`（點數不足，儲值可解）／`plan_not_allowed`（方案不含匯入，需升級方案）／`plan_daily_limit_reached`（今日方案用量已滿，明日重置；儲值無法解決，v1.16.4 新增）
`is_unlimited`	boolean	是否為吃到飽（不限點數）
`remain_quota`	float \| null	剩餘點數；吃到飽時為 `null`。v1.9.0 語意變更：被分配專屬額度的 API Key 回該把 key 實際可動用的額度（專屬額度，而非帳戶總餘額）；未分配額度的帳號數值不變
`duration_minutes`	integer	音檔預估時長（分鐘，無條件進位）
`estimated_points`	float	預估扣點（STT 基準；實際另含翻譯／語者，上傳時精算）

POST /api/v1/imports（上傳音檔）

功能說明

上傳音檔進行語音辨識與翻譯處理。上傳成功後會在背景處理，可透過查詢狀態 API 追蹤進度。

使用場景

上傳錄音檔進行轉錄
批次處理音檔

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數（multipart/form-data）

參數	類型	必填	說明
`file`	file	是	音檔（mp3/wav/m4a，最大 500MB）。格式依實際內容判斷，副檔名與內容不符時依內容處理
`transcription_languages`	string	是	轉錄語言（JSON 陣列，如 `["zh-TW"]`）
`translation_languages`	string	否	翻譯語言（JSON 陣列，如 `["en-US"]`）
`recognition_mode`	string	是	辨識模式：`single` / `multi_speaker`。帶 `multi_language` 或 `multi_channel` 會回 422 `import_recognition_mode_unsupported`
`summary_template`	string	否	摘要模板識別碼（最大 50 字元）
`summary_mode`	string	否	摘要模式：`builtin`（預設，走 `summary_template`）或 `custom`（走 `summary_prompt`）。未指定＝沿用 `summary_template`
`summary_prompt`	string	否	`custom` 模式的自訂 prompt 全文（最大 3000 字元，完整取代內建模板）。`custom` 必填、其他模式禁帶
`summary_prompt_slug`	string	否	`custom` 模式的自訂識別碼（最大 64 字元，pass-through 不校驗）。`custom` 必填、其他模式禁帶
`terminology`	string	否	術語庫（JSON 物件，格式見下方）
`fuzzy_correction`	string	否	模糊詞校正規則（JSON 物件）
`translation_dict`	string	否	翻譯字典（JSON 物件，格式見下方）
`callback_url`	string	否	Webhook 回呼 URL（最大 2048 字元）

Webhook 通知：設定 callback_url 後，音檔處理完成或失敗時會自動發送 HTTP POST 通知。亦可在 API Key 設定中指定 webhook_url 作為預設回呼。詳見 Webhook 指南。

文字處理參數格式

術語庫 (terminology)：提升特定詞彙的辨識準確度

{
  "zh-TW": [
    { "term": "語者分離" },
    { "term": "即時轉錄" }
  ]
}

以語言代碼為 key，術語陣列為 value
term：術語文字（必填，最大 100 字元）
每種語言最多 500 個術語，且所有語言合計也不得超過 500 筆
模糊詞校正每種語言最多 4000 條規則，且所有語言合計也不得超過 4000 條

以上數字是預設值：實際生效的上限可依環境調整，一律以 422 回應裡的訊息為準。

注意：兩個上限都會驗證：單一語言超過 500 筆、或所有語言合計超過 500 筆，都會回 422 並指出實際筆數。多語言字庫請以合計為準規劃。

模糊詞校正 (fuzzy_correction)：修正讀音與術語不同的錯字

通常不需手動設定 —— 讀音相同的錯字由 terminology 直接涵蓋，僅在錯字與正確詞讀音不同時需要。

{
  "zh-TW": [
    { "correct": "語者分離", "incorrect": ["語這分離", "語者分力"] }
  ]
}

以語言代碼為 key，校正規則陣列為 value
correct：正確詞彙（必填，最大 200 字元）
incorrect：錯誤變體列表（條件必填，每項最大 200 字元）

只給正確詞、不列錯字：correct 是中文（含漢字）時，incorrect 可以整個省略 —— 系統會依讀音自動比對，逐字稿中讀音相同或相近的寫法會被修正回 correct。
{ "fuzzy_correction": { "zh-TW": [{ "correct": "艾思通" }] } }
上例不必列出任何錯字，「愛思通」「愛時通」「愛司東」「愛似通」都會被修正。只有讀音差距較大的寫法（例如「愛自動」）或音節數不同的（例如「愛松」）才需要另外列進 incorrect。
注意：兩個條件缺一不可：語言要是中文（zh-TW / zh-CN / zh-HK 等），且 correct 要含漢字。不滿足時 incorrect 仍為必填 —— 因為那些情況省略了不會有任何效果，收下反而會讓你以為設定成功。日文、韓文、英文的錯字請明確列出。

case_insensitive：本條規則的變體是否忽略大小寫（選填，預設 false = 嚴格比對）

同一個錯誤變體出現在多條規則時：碰撞以 incorrect（錯誤變體）為準，不是 correct。大小寫旗標取嚴格優先（任一條沒開 case_insensitive，該變體即以嚴格比對處理）。因此把同一個 correct 拆成多條規則是安全的，只要各條的 incorrect 不重複。

翻譯字典 (translation_dict)：指定專有名詞的翻譯方式。以語言代碼分組，每個語言各自一份字典。

{
  "en-US": [
    { "source": "語者分離", "target": "Speaker Diarization" }
  ]
}

頂層鍵：目標語言代碼
source：原文詞彙（必填，最多 200 字元）
target：該語言的指定譯法（必填，最多 200 字元）
case_sensitive：是否只在大小寫完全相符時才套用（選填，預設 false = 不分大小寫）
每個語言最多 3000 個條目

舊格式仍然支援：先前的條目陣列格式（[{ "source": ..., "translations": { "語言代碼": ... } }]）繼續接受，內容與行為完全不變，既有介接不需要任何改動。

大小寫旗標對照：fuzzy_correction 與 translation_dict 的大小寫開關欄位名互為反義、預設值代表的行為也相反——
區塊欄位預設值預設行為
fuzzy_correction case_insensitive false 嚴格（區分大小寫）
translation_dict case_sensitive false 寬鬆（不分大小寫）
兩者都預設 false，但一個代表嚴格、另一個代表寬鬆。請勿共用同一個變數或直接鏡射——設錯不會有任何錯誤訊息，只會做出與預期相反的比對行為。
注意：翻譯字典是以提示詞引導模型翻譯，屬盡力而為而非字面替換，大小寫旗標同樣是提示。需要確定性替換請改用 fuzzy_correction。

區塊	欄位	預設值	預設行為
`fuzzy_correction`	`case_insensitive`	`false`	嚴格（區分大小寫）
`translation_dict`	`case_sensitive`	`false`	寬鬆（不分大小寫）

點數檢查：上傳時會自動檢查點數餘額。若點數不足會返回 auth_insufficient_credit 錯誤（HTTP 402）。
建議：上傳前可先使用 check-quota API 預檢查點數是否足夠，避免上傳大檔案後才發現點數不足。

請求範例

基本請求

curl -X POST "https://vas-poc.vurbo.ai/api/v1/imports" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -F "file=@meeting.mp3" \
  -F 'transcription_languages=["zh-TW"]' \
  -F 'translation_languages=["en-US"]' \
  -F "recognition_mode=multi_speaker"

含文字處理設定的請求

curl -X POST "https://vas-poc.vurbo.ai/api/v1/imports" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -F "file=@meeting.mp3" \
  -F 'transcription_languages=["zh-TW"]' \
  -F 'translation_languages=["en-US"]' \
  -F "recognition_mode=multi_speaker" \
  -F 'terminology={"zh-TW": [{"term": "語者分離"}]}' \
  -F 'fuzzy_correction={"zh-TW": [{"correct": "語者分離", "incorrect": ["語這分離"]}]}' \
  -F 'translation_dict={"en-US": [{"source": "語者分離", "target": "Speaker Diarization"}]}'

成功回應（HTTP 202）

{
  "data": {
    "import_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "stage": null,
    "progress": 0,
    "message": null,
    "original_filename": "meeting.mp3",
    "file_size": "15.2 MB",
    "task_id": null,
    "error_code": null,
    "error_message": null,
    "created_at": "2026-01-03T10:00:00.000Z",
    "updated_at": "2026-01-03T10:00:00.000Z",
    "downgraded_features": []
  }
}

downgraded_features（v1.9.0）：使用吃到飽方案且方案含匯入、但不含部分子功能（如語者分離 speaker_diarization、翻譯 translation）時，該子功能會被略過、匯入照常進行，被略過的功能列於此陣列；空陣列＝無降級。

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`import_file_too_large`	413	檔案大小超過限制	壓縮或分割檔案
`import_invalid_format`	415	不支援的音檔格式	使用 mp3/wav/m4a 格式
`import_recognition_mode_unsupported`	422	匯入不支援此辨識模式（`multi_language`、`multi_channel`）；`data.details` 帶 `field` 與 `supportedModes`	改用 `single` 或 `multi_speaker`
`auth_insufficient_credit`	402	點數不足	儲值點數後再使用
`plan_feature_not_allowed`	403	吃到飽方案不含檔案匯入	升級方案；可用 `GET /api/v1/me/plan` 查方案內容
`plan_daily_limit_reached`	402	已達方案每日用量上限	依方案規則重置（隔日）後再上傳

GET /api/v1/imports/{importId}（查詢匯入狀態）

功能說明

查詢指定匯入任務的處理狀態與進度。

匯入產生的任務被刪除後，對應的匯入紀錄會一併移除，查詢會回 404 import_not_found。

使用場景

追蹤上傳音檔的處理進度
取得處理完成後的任務 ID

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`importId`	string	是	匯入 ID（UUID）

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/imports/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應

{
  "data": {
    "import_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "stage": "transcribing",
    "progress": 45,
    "message": "正在辨識語音...",
    "original_filename": "meeting.mp3",
    "file_size": "15.2 MB",
    "task_id": null,
    "error_code": null,
    "error_message": null,
    "created_at": "2026-01-03T10:00:00.000Z",
    "updated_at": "2026-01-03T10:05:00.000Z"
  }
}

欄位	類型	說明
`status`	string	狀態：`pending` / `processing` / `completed` / `failed`
`stage`	string	處理階段：`converting` / `transcribing` / `translating` / `summarizing`
`progress`	integer	進度百分比（0-100）
`task_id`	string	處理完成後的任務 ID（可用於 Task API）
`error_code`	string	失敗時的錯誤碼
`error_message`	string	失敗時的錯誤訊息（一般說明，不含內部細節；排查時請提供 `import_id`）

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`import_not_found`	404	找不到匯入任務	確認 importId 正確；匯入產生的任務若已刪除，匯入紀錄也會一併移除

GET /api/v1/imports（取得匯入列表）

功能說明

取得使用者的匯入任務列表（分頁）。已刪除任務所對應的匯入紀錄不會出現在列表中。

使用場景

顯示匯入歷史記錄
查看所有匯入任務狀態

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`per_page`	integer	否	每頁筆數（預設 20）

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/imports?per_page=20" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應

{
  "data": [
    {
      "import_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "original_filename": "meeting.mp3",
      "file_size": "15.2 MB",
      "task_id": "660e8400-e29b-41d4-a716-446655440001",
      "created_at": "2026-01-03T10:00:00.000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 100
  }
}

Audio API

音訊檔案串流播放，支援 HTTP Range Request。

GET /api/v1/sse/audio/{taskId}（音訊串流播放）

功能說明

串流播放指定任務的錄音檔案，支援 HTTP Range Request 實現拖曳播放。

注意：雖然路徑包含 /sse/，但此端點返回的是音訊檔案（非 SSE 串流）。

使用場景

播放錄音音訊
支援拖曳播放進度

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`taskId`	string	是	錄音 ID（即 `recordings.id`，UUID）

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/sse/audio/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

回應格式

完整檔案（HTTP 200）：

HTTP/1.1 200 OK
Content-Type: audio/mp4
Content-Length: 1234567
Accept-Ranges: bytes
Cache-Control: no-cache

注意：所有錄音音檔一律以 M4A 容器（AAC 編碼）回傳，Content-Type 固定為 audio/mp4。

部分檔案（HTTP 206 - Range Request）：

HTTP/1.1 206 Partial Content
Content-Type: audio/mp4
Content-Length: 1024
Content-Range: bytes 0-1023/1234567
Accept-Ranges: bytes

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`recording_not_found`	404	找不到錄音	確認 taskId 正確
`recording_audio_not_ready`	422	音檔尚未上傳完成	稍後重試
`storage_download_failed`	500	儲存服務下載失敗	稍後重試

前端範例

async function playAudio(taskId, apiKey) {
  const response = await fetch(
    `https://vas-poc.vurbo.ai/api/v1/sse/audio/${taskId}`,
    {
      headers: {
        'X-API-Key': apiKey
      }
    }
  );

  const blob = await response.blob();
  const audioUrl = URL.createObjectURL(blob);
  const audio = new Audio(audioUrl);
  audio.play();
}

TTS API

TTS（Text-to-Speech）API 提供語音合成相關的查詢功能。

GET /api/v1/tts/voices（取得 TTS 語音列表）

功能說明

取得指定語言可用的 TTS 語音列表。每種語言有多個語音可選擇，包含不同性別和風格。

使用場景

讓用戶選擇偏好的 TTS 語音
顯示可用語音選項

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`language`	string	是	語言代碼（如 `en-US`）

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/tts/voices?language=en-US" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應

{
  "data": {
    "language": "en-US",
    "voices": [
      {
        "voice_name": "en-US-JennyNeural",
        "display_name": "Jenny",
        "gender": "Female",
        "is_default": true,
        "sample_url": "https://vas-poc.vurbo.ai/api/v1/tts/voices/en-US-JennyNeural/sample"
      },
      {
        "voice_name": "en-US-GuyNeural",
        "display_name": "Guy",
        "gender": "Male",
        "is_default": false,
        "sample_url": "https://vas-poc.vurbo.ai/api/v1/tts/voices/en-US-GuyNeural/sample"
      },
      {
        "voice_name": "en-US-AriaNeural",
        "display_name": "Aria",
        "gender": "Female",
        "is_default": false,
        "sample_url": "https://vas-poc.vurbo.ai/api/v1/tts/voices/en-US-AriaNeural/sample"
      },
      {
        "voice_name": "en-US-DavisNeural",
        "display_name": "Davis",
        "gender": "Male",
        "is_default": false,
        "sample_url": "https://vas-poc.vurbo.ai/api/v1/tts/voices/en-US-DavisNeural/sample"
      },
      {
        "voice_name": "en-US-SaraNeural",
        "display_name": "Sara",
        "gender": "Female",
        "is_default": false,
        "sample_url": "https://vas-poc.vurbo.ai/api/v1/tts/voices/en-US-SaraNeural/sample"
      },
      {
        "voice_name": "en-US-TonyNeural",
        "display_name": "Tony",
        "gender": "Male",
        "is_default": false,
        "sample_url": "https://vas-poc.vurbo.ai/api/v1/tts/voices/en-US-TonyNeural/sample"
      }
    ]
  }
}

欄位	類型	說明
`voice_name`	string	語音識別碼（用於 API）
`display_name`	string	語音顯示名稱
`gender`	string	性別：`Female` / `Male`
`is_default`	boolean	是否為該語言的預設語音
`sample_url`	string	語音示範音訊 URL（可直接播放試聽）

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`validation_failed`	400	缺少 `language` 參數或參數格式錯誤	提供有效的 `language` 參數

收到不支援的語言代碼時，本端點回傳 HTTP 200 與空的 voices 陣列，不會回傳錯誤——這包含「有語音可用、但因缺少轉錄支援而無法作為 TTS 目標」的 locale。有效代碼請參考支援語言清單。

GET /api/v1/tts/voices/{voiceName}/sample（取得語音示範音訊）

功能說明

取得指定語音的示範音訊檔案（MP3 格式）。首次請求會即時合成並快取，後續請求直接從快取返回。

此端點不計入 TTS 費用。

使用場景

讓用戶在選擇語音前先試聽效果
提供語音瀏覽和比較功能

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`voiceName`	string	是	語音名稱（如 `en-US-JennyNeural`）

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/tts/voices/zh-TW-HsiaoChenNeural/sample" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  --output sample.mp3

成功回應

回應為 MP3 音訊二進位資料（非 JSON）。

Header	值
`Content-Type`	`audio/mpeg`
`Content-Length`	音訊檔案大小（bytes）
`Cache-Control`	`public, max-age=86400`

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`tts_voice_not_found`	404	語音不存在，或該語音所屬語言無法作為 TTS 目標語言（`GET /api/v1/tts/voices` 不會列出的語音一律視為不存在）	以 `GET /api/v1/tts/voices?language={code}` 回傳的 `voice_name` 為準
`tts_sample_generation_failed`	500	語音示範生成失敗	稍後重試
-	429	請求頻率過高	等待後重試（限制 30 次/分鐘）

限流

每分鐘 30 次/每用戶。超過限制時回傳 HTTP 429。

Broadcasts API

廣播 API 提供即時字幕串流功能的管理，包含建立、查詢、更新和撤銷廣播。

GET /api/v1/broadcasts（廣播列表）

功能說明

查詢當前 API Key 擁有者的廣播列表（不包含已撤銷的頻道），支援分頁。

使用場景

查看所有已建立的廣播
管理多個廣播頻道
監控廣播狀態

認證方式

Header：X-API-Key: YOUR_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": "0: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，用於即時字幕串流。建立後會產生一個分享連結，觀眾可透過此連結接收即時字幕和翻譯。

完整請求／回應規格（含 transcription_languages 複數欄位、翻譯語言上限 12 種、各違規情境的錯誤碼）見 reference/rest/broadcasts.md。本頁範例保留的單數 transcription_language 為向後相容欄位（等同陣列首元素）。

使用場景

建立講座/演講的即時字幕
建立會議的即時翻譯串流
建立直播的即時字幕

認證方式

Header：X-API-Key: YOUR_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	否	最大觀眾人數（1 ~ 帳戶觀眾上限；未指定時預設為該上限）
`speaker_diarization`	boolean	否	講者分離（`true` 或 `false`，預設 `false`）
`tts_config`	object	否	TTS 預設設定（key 為語言代碼）
`tts_config.*.voice`	string	否	TTS 語音名稱（不指定使用預設語音）
`summary_template`	string	否	摘要模板 slug（最大 50 字元，需為已啟用的 `summary` 類別模板）
`summary_language`	string	否	摘要輸出語言，須為支援語言清單中的語言代碼（不指定時預設使用 `transcription_language`）
`callback_url`	string	否	Webhook 回呼 URL（最大 2048 字元）

Webhook 通知：設定 callback_url 後，廣播錄音處理完成或失敗時會自動發送 HTTP POST 通知。亦可在 API Key 設定中指定 webhook_url 作為預設回呼。詳見 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"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    },
    "summary_template": "lecture",
    "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"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    },
    "speaker_diarization": false,
    "summary_template": "lecture",
    "summary_language": "zh-TW",
    "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": "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：直播中才有值，為這一次開播的錄音（接管後為新的錄音）；預備階段或未在直播時為 `null`
`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 狀態碼	說明	處理建議
`auth_missing_api_key`	401	API Key 未提供	確認 Header 包含 API Key
`auth_invalid_api_key`	401	API Key 無效	確認 API Key 正確
`validation_failed`	422	參數驗證失敗	確認參數格式正確
`plan_feature_not_allowed`	403	吃到飽方案不含廣播（廣播一律不含在方案內）	廣播照點數計費；請改用點數制的 API Key

GET /api/v1/broadcasts/{id}（查詢廣播狀態）

功能說明

查詢指定廣播的詳細資訊和目前狀態。

使用場景

查看廣播是否已開始
監控觀眾人數
確認廣播狀態

認證方式

Header：X-API-Key: YOUR_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"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    },
    "speaker_diarization": true,
    "summary_template": "lecture",
    "summary_language": "zh-TW",
    "max_viewers": 100,
    "access_type": "public",
    "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: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`id`	string	是	廣播 ID（路徑參數）
`access_type`	string	否	存取類型：`public` 或 `password`
`pass_code`	string	條件	密碼（4-12 字元，限英文字母、數字與常見標點（不接受中文與空白），當 `access_type` 為 `password` 時必填）
`max_viewers`	integer	否	最大觀眾人數（1 ~ 帳戶觀眾上限）
`transcription_language`	string	否	轉錄語言（如 `zh-TW`、`en-US`、`ja-JP`）
`translation_languages`	array	否	翻譯語言列表（如 `["en-US", "ja-JP"]`）
`speaker_diarization`	boolean	否	講者分離開關（`true` 或 `false`）
`tts_config`	object	否	TTS 預設設定（會覆蓋現有設定，`null` 表示清除）
`summary_template`	string	否	摘要模板 slug（最大 50 字元，空字串 `""` 表示清除）
`summary_language`	string	否	摘要輸出語言，須為支援語言清單中的語言代碼（空字串 `""` 表示清除）

注意：未提供任何可更新欄位時回 200 且資料不變。頻道名稱建立後無法修改，帶 name 會被忽略。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 '{
    "access_type": "password",
    "pass_code": "mySecret123"
  }'

# 調整觀眾人數上限
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 '{
    "max_viewers": 200
  }'

# 變更轉錄語言和翻譯語言
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 '{
    "transcription_language": "en-US",
    "translation_languages": ["zh-TW", "ja-JP", "ko-KR"]
  }'

# 開啟講者分離
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 '{
    "speaker_diarization": true
  }'

# 更新 TTS 預設設定
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 '{
    "tts_config": {
      "zh-TW": {"voice": "zh-TW-HsiaoChenNeural"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    }
  }'

成功回應（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"},
      "ja-JP": {"voice": "ja-JP-NanamiNeural"}
    },
    "speaker_diarization": true,
    "summary_template": "lecture",
    "summary_language": "zh-TW",
    "access_type": "password",
    "pass_code": "mySecret123",
    "max_viewers": 200,
    "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 正確
`validation_failed`	422	參數驗證失敗	確認參數格式正確

DELETE /api/v1/broadcasts/{id}（撤銷廣播）

功能說明

撤銷尚未開始的廣播。只有 pending 狀態的廣播可以撤銷。

使用場景

取消尚未開始的廣播
清理不需要的廣播

認證方式

Header：X-API-Key: YOUR_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",
    "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: YOUR_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 筆

Viewer API

觀眾端 API，不需要 API Key 認證。用於觀眾查看廣播資訊和密碼驗證。

兩個端點都可從任何網域的網頁直接呼叫，觀眾頁可以放在您自己的網域；請求不要帶憑證。詳見從瀏覽器呼叫。

GET /api/v1/viewer/broadcasts/{token}（取得廣播公開資訊）

功能說明

取得指定廣播的公開資訊，供觀眾端顯示頻道資訊。

使用場景

觀眾進入廣播頁面前顯示頻道資訊
判斷是否需要輸入密碼

認證方式

無需認證

請求參數

參數	類型	必填	說明
`token`	string	是	廣播 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 語音列表

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	請求過於頻繁：同一頻道每分鐘的上限約為頻道最大觀眾數的 2 倍（最少 200 次）；同一來源查詢不存在的頻道過多時也會暫時回 429。詳見頻率限制	依回應標頭 `Retry-After` 的秒數等待後再試

POST /api/v1/viewer/broadcasts/{token}/verify（密碼驗證）

功能說明

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

使用場景

觀眾進入密碼保護的廣播前驗證密碼
取得 SSE 連線所需的 viewer_access_token

認證方式

無需認證

請求參數

參數	類型	必填	說明
`token`	string	是	廣播 Token（路徑參數）
`password`	string	是	頻道密碼（最多 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-01-04T10:00:00.000Z"
  }
}

公開頻道（不需密碼）：

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

欄位	類型	說明
`viewer_access_token`	string	觀眾存取 Token（24 小時有效）
`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	請求過於頻繁，或密碼錯誤次數過多而暫時鎖定（同一來源 5 分鐘內錯 30 次，或同一頻道 5 分鐘內累計錯 100 次）。詳見頻率限制	依回應標頭 `Retry-After` 的秒數等待後再試；鎖定期間即使密碼正確也要等待

Recording Speaker 編輯 API

Recording Speaker 編輯 API 提供離線 Recording 的逐字稿語者編輯功能，與即時模式 WebSocket 的 Speaker 編輯功能行為一致。

限制：此 API 僅適用於多人辨識模式（multi_speaker）的錄音。單人模式的錄音會回傳 speaker_diarization_required 錯誤。

PATCH /api/v1/tasks/{taskId}/speakers/rename（全域重命名說話者）

功能說明

將指定說話者 ID 全域重命名為新名稱。此操作會更新 speakerAliases 映射，並將所有使用該說話者 ID 的逐字稿條目的 speaker 欄位更新為新名稱。

使用場景

將自動辨識的說話者 ID（如 Guest-1）改為真實姓名
統一修改某位說話者的顯示名稱

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`taskId`	string	是	任務 UUID（路徑參數）
`speaker_id`	string	是	原始語者 ID（如 `Guest-1`），可同時接受目前的顯示標籤做連續改名；最大 100 字元
`new_label`	string	是	新顯示標籤；最大 100 字元，不得含控制字元（`\x00-\x1F`、`\x7F`）或換行（會寫入逐字稿與匯出檔）

請求範例

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/speakers/rename" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "speaker_id": "Guest-1",
    "new_label": "王經理"
  }'

成功回應（HTTP 200）

{
  "data": {
    "speaker_id": "Guest-1",
    "new_label": "王經理",
    "affected_sids": [1, 3, 5, 8, 12]
  }
}

欄位	類型	說明
`speaker_id`	string	解析後的原始語者 ID（即使 request 送顯示標籤，回應仍是原始 ID）
`new_label`	string	新顯示標籤
`affected_sids`	array<int>	受影響的句子 SID 列表

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`recording_not_found`	404	找不到指定的錄音	確認 taskId 正確
`speaker_transcript_not_found`	404	找不到逐字稿	確認錄音已完成轉錄
`speaker_diarization_required`	422	此功能僅支援語者分離錄音	僅適用於多人辨識模式的錄音
`speaker_name_empty`	422	`new_label` 為空	提供有效的 `new_label`
`validation_failed`	422	參數驗證失敗	檢查 `speaker_id` / `new_label` 長度與字符（不得含控制字元）
`transcript_revision_conflict`	409	同一份逐字稿正有其他寫入在進行	稍後重試即可；本次變更未生效
`storage_upload_failed`	500	逐字稿寫回儲存服務失敗	稍後重試；本次變更未生效

PATCH /api/v1/tasks/{taskId}/speakers/reassign（修改單句語者身份）

功能說明

修改單一句子的語者身份，將句子指派給現有語者。

使用場景

修正語者辨識錯誤
將某句話重新歸屬到正確的說話者

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`taskId`	string	是	任務 UUID（路徑參數）
`sid`	integer	是	句子編號
`target_speaker_id`	string	是	目標語者原始 ID（取自 `init_sentence.speaker_id`，不接受顯示標籤）；最大 100 字元

請求範例

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/speakers/reassign" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "sid": 5,
    "target_speaker_id": "Guest-2"
  }'

成功回應（HTTP 200）

{
  "data": {
    "sid": 5,
    "old_speaker_id": "Guest-1",
    "new_speaker_id": "Guest-2",
    "new_speaker_label": "李小華"
  }
}

欄位	類型	說明
`sid`	integer	被修改的句子 ID
`old_speaker_id`	string	原始語者 ID
`new_speaker_id`	string	新的原始語者 ID
`new_speaker_label`	string	新語者顯示標籤（套用 `speaker_aliases` 後；無 alias 時等於 `new_speaker_id`）

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`recording_not_found`	404	找不到指定的錄音	確認 taskId 正確
`speaker_transcript_not_found`	404	找不到逐字稿	確認錄音已完成轉錄
`speaker_diarization_required`	422	此功能僅支援語者分離錄音	僅適用於多人辨識模式的錄音
`speaker_sid_not_found`	422	找不到指定的句子	確認 sid 存在
`speaker_not_found`	422	找不到指定的語者	確認 target_speaker_id 存在
`invalid_data`	422	不支援建立新語者	使用已存在的語者 ID
`validation_failed`	422	參數驗證失敗	確認參數格式正確
`transcript_revision_conflict`	409	同一份逐字稿正有其他寫入在進行	稍後重試即可；本次變更未生效
`storage_upload_failed`	500	逐字稿寫回儲存服務失敗	稍後重試；本次變更未生效

PATCH /api/v1/tasks/{taskId}/speakers/merge（合併語者）

功能說明

把 source 語者的所有句子歸屬到 target 語者；source 的別名（若有）會轉移到 target。適用於語者分離模型把同一人誤判為兩個 speaker 的情境。

vs. reassign：reassign 只改單句；merge 改該語者所有句子。 vs. rename：rename 只改顯示名稱；merge 把多個語者整併。

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`taskId`	string	是	任務 ID（UUID，路徑參數）
`source_speaker_id`	string	是	被合併的原始語者 ID 或當前顯示標籤（如 `Guest-2` 或 `王經理`），最大 100 字元
`target_speaker_id`	string	是	合併目標語者的原始 ID 或當前顯示標籤（如 `Guest-1`），最大 100 字元

請求範例

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/speakers/merge" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "source_speaker_id": "Guest-2",
    "target_speaker_id": "Guest-1"
  }'

成功回應（HTTP 200）

{
  "data": {
    "source_speaker_id": "Guest-2",
    "target_speaker_id": "Guest-1",
    "target_speaker_label": "王經理",
    "affected_sids": [3, 5, 7]
  }
}

欄位	類型	說明
`source_speaker_id`	string	被合併的原始語者 ID（即使請求送顯示標籤也會解析回原始 ID）
`target_speaker_id`	string	合併目標的原始語者 ID
`target_speaker_label`	string	目標語者顯示標籤（套用 `speaker_aliases` 後；無 alias 時等於原始 ID）
`affected_sids`	array<int>	受影響的句子 SID 列表：原屬來源語者的句子，加上顯示名稱因合併而改變的目標語者原有句子（例如來源語者的自訂名稱轉給目標語者時）

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`merge_speakers_same_id`	400	source 與 target 為相同語者	提供不同的語者 ID
`speaker_name_empty`	422	source 或 target 為空字串	提供有效的語者 ID
`speaker_not_found`	422	source 或 target 在錄音中不存在	確認語者 ID 正確
`recording_not_found`	404	找不到錄音	確認 taskId 正確
`speaker_transcript_not_found`	404	找不到逐字稿	確認錄音已完成轉錄
`speaker_diarization_required`	422	該錄音非多人對話模式	僅適用 `recognition_mode: multi_speaker`
`validation_failed`	422	參數驗證失敗	確認 source / target 皆已提供
`transcript_revision_conflict`	409	同一份逐字稿正有其他寫入在進行	稍後重試即可；本次變更未生效
`storage_upload_failed`	500	逐字稿寫回儲存服務失敗	稍後重試；本次變更未生效

完整規格見 reference/rest/speakers.md。

僅允許 processing_status === completed 的錄音；進行中的錄音回 recording_not_completed
樂觀鎖：可帶 expected_revision，不符回 409 transcript_revision_conflict

認證方式

Header：X-API-Key

請求參數

參數	位置	類型	必填	說明
`taskId`	path	string	是	任務 ID（UUID）
`sid`	path	number	是	句子 ID（1-based）
`original_text`	body	string	是	修正後的原文，1–2000 字元
`expected_revision`	body	number	否	樂觀鎖；當前 transcript revision

請求範例

curl -X PATCH "https://vas-poc.vurbo.ai/api/v1/tasks/{taskId}/entries/5" \
  -H "X-API-Key: vas_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "original_text": "修正後的文字", "expected_revision": 3 }'

成功回應（HTTP 200）

{
  "data": {
    "sid": 5,
    "original_text": "修正後的文字",
    "original_text_raw": "原始 STT 輸出",
    "original_text_edited_at": "2026-05-06T10:30:00.000000Z",
    "translated_texts": { "en-US": "已過期的舊翻譯" },
    "revision": 4
  }
}

既有翻譯不會自動更新；前端應在收到回應後呼叫 GET /api/v1/sse/recordings/{taskId}/entries/{sid}/retranslate 重翻。

錯誤回應

錯誤碼	HTTP	說明
`recording_not_found`	404	錄音不存在或不屬於該使用者
`recording_not_completed`	422	錄音尚未完成處理
`entry_not_found`	404	找不到指定的句子
`entry_text_empty`	422	原文為空
`entry_text_too_long`	422	原文超過 2000 字元
`transcript_revision_conflict`	409	revision 不符，或同一份逐字稿正有其他寫入在進行
`speaker_transcript_not_found`	404	找不到逐字稿

完整規格與「編輯 + 自動重翻」工作流範例見 reference/rest/entries.md。

Summary Template API

摘要模板 API 提供查詢可用的摘要模板列表，用於音檔匯入時選擇摘要樣式。

GET /api/v1/summary-templates（取得摘要模板列表）

完整 schema 請參考 reference/rest/summary-templates.md。

參數	位置	類型	必填	預設	說明
`category`	query	string	否	`summary`	模板類別篩選：`summary` / `medical` / `legal` / `all`

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/summary-templates?category=medical" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應

{
  "data": [
    { "slug": "general",          "name": "通用摘要", "description": "...", "category": "summary" },
    { "slug": "meeting",          "name": "會議摘要", "description": "...", "category": "summary" },
    { "slug": "meeting_minutes",  "name": "會議紀要", "description": "...", "category": "summary" },
    { "slug": "speech",           "name": "演講摘要", "description": "...", "category": "summary" },
    { "slug": "interview",        "name": "訪談摘要", "description": "...", "category": "summary" },
    { "slug": "course",           "name": "課程摘要", "description": "...", "category": "summary" }
  ]
}

欄位	類型	說明
`slug`	string	模板識別碼（用於 API 參數）
`name`	string	模板名稱
`description`	string	模板說明（可能為 null）
`category`	string	模板類別（`summary` / `medical` / `legal`）

錯誤回應

錯誤碼	HTTP	說明	處理建議
`auth_missing_api_key`	401	API Key 未提供	確認 Header 包含 API Key
`auth_invalid_api_key`	401	API Key 無效	確認 API Key 正確
`invalid_category`	400	`category` 不在白名單內	改用 `summary` / `medical` / `legal` / `all`

GET /api/v1/summary-templates/{slug}（取得單一摘要模板詳細內容）

提供內建模板的完整原始文字，供企業客戶整合時參考。完整 schema 請參考 reference/rest/summary-templates.md。

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	位置	類型	必填	說明
`slug`	path	string	是	模板識別碼

請求範例

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

成功回應

{
  "data": {
    "slug": "medical_consultation",
    "name": "看診諮詢",
    "description": "看診諮詢記錄模板",
    "category": "medical",
    "system_prompt": "You are a professional medical records specialist...",
    "template_prompt": "[Task]\nGenerate a structured summary...",
    "output_format": "[Summary Template Begin]\n## Patient Information\n..."
  }
}

錯誤回應

錯誤碼	HTTP	說明
`template_not_found`	404	指定 slug 的模板不存在或已停用（`is_active=false`）

字庫驗證 API

POST /api/v1/glossary/validate（存檔前驗證字庫）

在存檔前檢查一份字庫（術語庫、模糊詞校正、翻譯字典）有沒有格式問題或內部衝突。適用於貴方的字庫管理介面在儲存前呼叫，不需要在每次建立錄音或匯入音檔前呼叫。

字庫的多數設定問題不會產生錯誤訊息，只會在錄音或翻譯時安靜地產生非預期結果。本端點把這類問題在使用者按下儲存的當下就指出來，並附上是第幾筆。

注意：主機為即時服務網域（與 wss:// 同一個網域，協定換成 https://），與其他 REST 端點可能不同。

免費，不扣點、不建立任何任務或錄音
頻率限制為每把 API Key 每分鐘 120 次，獨立配額，與其他 REST 端點分開計算
回應不含人語文案，由貴方依衝突代碼自行組句

curl -X POST "https://<即時服務網域>/api/v1/glossary/validate" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{"fuzzy_correction":{"zh-TW":[{"correct":"報價","incorrect":["抱歉"]},{"correct":"抱歉"}]}}'

八種可偵測的衝突、完整請求／回應規格與所有欄位定義見字庫驗證 API；字庫本身的設定方式見字庫使用指南。

錯誤處理

統一錯誤格式

所有 API 錯誤遵循統一格式：

簡易格式（外部 API）：

{
  "error_code": "auth_invalid_api_key",
  "message": "API Key 無效或已過期"
}

詳細格式（內部 API）：

{
  "type": "error",
  "data": {
    "error_code": "auth_invalid_api_key",
    "severity": "fatal",
    "message": "Invalid or expired API key",
    "context": "auth",
    "request_id": "req_abc123xyz789",
    "timestamp": "2025-12-13T10:30:45.123Z",
    "details": null
  }
}

錯誤碼總覽

認證錯誤

error_code	HTTP 狀態	severity	說明
`auth_missing_api_key`	401	fatal	API Key 未提供
`auth_invalid_api_key`	401	fatal	API Key 無效
`auth_key_expired`	401	fatal	API Key 已過期

資源錯誤

error_code	HTTP 狀態	說明
`recording_not_found`	404	錄音不存在
`recording_audio_not_ready`	422	音檔尚未準備好

廣播錯誤

error_code	HTTP 狀態	說明
`broadcast_not_found`	404	找不到廣播
`broadcast_session_ended`	410	廣播已結束
`broadcast_unauthorized`	403	無權限存取

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

支援語言清單

SSE API 總覽