API 文件

Rest Api

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

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`	摘要模板查詢
Generate Summary API	`/api/v1/summary`	Header `Authorization: Bearer`	對任意逐字稿生成摘要（Bearer 認證）
Broadcast REST API	`/broadcast`	Token（路徑參數）	廣播即時狀態

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

功能說明

取得目前使用者的錄音任務列表。可透過 status 參數篩選不同處理階段的任務。

請求參數（Query）

參數	類型	必填	預設值	說明
`status`	string	否	`completed`	篩選任務狀態：`completed`、`active`、`all`

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

請求範例

# 預設查詢（已完成的任務）
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"

成功回應

欄位	類型	說明
`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 正確

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

請求參數

參數	類型	必填	說明
`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 正確
`recording_unauthorized`	403	無權限操作此錄音	確認任務屬於該用戶

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

功能說明

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

請求參數

參數	位置	類型	必填	說明
`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 會被忽略。

請求參數

參數	位置	類型	必填	說明
`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
  }
}

回應欄位說明

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

錯誤回應

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

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

請求參數

參數	類型	必填	說明
`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}'

成功回應

{
  "is_pinned": true
}

錯誤回應

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

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

請求參數

參數	類型	必填	說明
`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"

成功回應

{
  "is_unread": false
}

錯誤回應

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

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

請求參數

參數	類型	必填	說明
`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 以便拖曳快進；回應不強制下載。

請求參數

參數	位置	類型	必填	說明
`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 狀態的任務重新排入處理佇列（ProcessRecordingJob）。操作成功後 processing_status 變為 processing，processing_error 清空。使用 afterCommit() 確保 queue worker 不會在 DB 交易 commit 前讀到舊值。

前置條件：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`

音檔匯入 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,
    "remaining_budget": 48.48,
    "is_unlimited": false,
    "duration_minutes": 25,
    "estimated_cost": 0.4236,
    "remaining_minutes": 2864
  }
}

欄位	類型	說明
`allowed`	boolean	是否允許上傳（預算未超額時為 true）
`remaining_budget`	float \| null	剩餘月度預算（USD），無預算限制時為 `null`
`is_unlimited`	boolean	是否為無預算限制
`duration_minutes`	integer	音檔預估時長（分鐘，無條件進位）
`estimated_cost`	float	預估 STT 處理費用（USD）
`remaining_minutes`	integer \| null	剩餘預算可用的等效 STT 分鐘數，無預算限制時為 `null`

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`
`summary_template`	string	否	摘要模板識別碼（最大 50 字元）
`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": "語者分離", "boost": 1.5 },
    { "term": "即時轉錄", "boost": 1.5 }
  ]
}

以語言代碼為 key，術語陣列為 value
term：術語文字（必填，最大 100 字元）
boost：權重（選填，預設 1.0）
每種語言最多 500 個術語

模糊詞校正 (fuzzy_correction)：自動修正常見的辨識錯誤

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

以語言代碼為 key，校正規則陣列為 value
correct：正確詞彙（必填）
incorrect：錯誤變體列表（必填）

翻譯字典 (translation_dict)：指定專有名詞的翻譯方式

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

source：原文詞彙（必填）
translations：各語言對應翻譯（以語言代碼為 key）
最多 50 個條目

預算檢查：上傳時會自動檢查月度預算。若預算已超額會返回 auth_budget_exceeded 錯誤（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": "語者分離", "boost": 1.5}]}' \
  -F 'fuzzy_correction={"zh-TW": [{"correct": "語者分離", "incorrect": ["語這分離"]}]}' \
  -F 'translation_dict=[{"source": "語者分離", "translations": {"en-US": "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"
  }
}

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`import_file_too_large`	413	檔案大小超過限制	壓縮或分割檔案
`import_invalid_format`	415	不支援的音檔格式	使用 mp3/wav/m4a 格式
`auth_budget_exceeded`	402	月度預算已超額	等待下月預算重置或調整預算

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

功能說明

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

使用場景

追蹤上傳音檔的處理進度
取得處理完成後的任務 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	失敗時的錯誤訊息

錯誤回應

錯誤碼	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`	string	語音識別碼（用於 API）
`display_name`	string	語音顯示名稱
`gender`	string	性別：`Female` / `Male`
`is_default`	boolean	是否為該語言的預設語音
`sample_url`	string	語音示範音訊 URL（可直接播放試聽）

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`tts_unsupported_language`	400	不支援的語言	使用有效的語言代碼

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

使用場景

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

認證方式

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 語音名稱（不指定使用預設語音）
`tts_config.*.speaking_rate`	number	否	TTS 語速（0.5~2.0，預設 1.0）
`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", "speaking_rate": 1.0},
      "ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
    },
    "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", "speaking_rate": 1.0},
      "ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
    },
    "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（直播中才有值）
`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	參數驗證失敗	確認參數格式正確

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-AvaMultilingualNeural"},
      "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	否	摘要輸出語言（空字串 `""` 表示清除）

注意：至少需要提供一個欄位。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", "speaking_rate": 1.0},
      "ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.2}
    }
  }'

成功回應（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", "speaking_rate": 1.0},
      "ja-JP": {"voice": "ja-JP-NanamiNeural", "speaking_rate": 1.0}
    },
    "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 正確
`broadcast_cannot_update`	422	只有 pending/active/paused 可更新	檢查廣播目前狀態
`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",
    "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 的語言（直播中動態取得，否則使用預設值）
`tts_voices`	object	各翻譯語言的 TTS 語音列表

tts_voices 結構說明：

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

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

錯誤回應

錯誤碼	HTTP 狀態碼	說明	處理建議
`broadcast_token_invalid`	404	Token 無效	確認 Token 正確
`broadcast_token_revoked`	410	Token 已撤銷	廣播已被撤銷

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_password_incorrect`	401	密碼錯誤	重新輸入正確密碼
`validation_failed`	422	參數驗證失敗	確認密碼格式正確

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（路徑參數，與舊命名 `recordingId` 為同一值）
`speaker_id`	string	是	原始語者 ID（如 `Guest-1`），可同時接受目前的顯示標籤做連續改名；最大 100 字元
`new_label`	string	是	新顯示標籤；最大 100 字元，不得含控制字元（`\x00-\x1F`、`\x7F`）或換行（會寫入 transcript blob 與匯出檔）

請求範例

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	找不到指定的錄音	確認 recordingId 正確
`speaker_transcript_not_found`	404	找不到逐字稿	確認錄音已完成轉錄
`speaker_diarization_required`	422	此功能僅支援語者分離錄音	僅適用於多人辨識模式的錄音
`speaker_name_empty`	422	`new_label` 為空	提供有效的 `new_label`
`validation_failed`	422	參數驗證失敗	檢查 `speaker_id` / `new_label` 長度與字符（不得含控制字元）

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

功能說明

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

使用場景

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

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	類型	必填	說明
`taskId`	string	是	任務 UUID（路徑參數，與舊命名 `recordingId` 為同一值）
`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	找不到指定的錄音	確認 recordingId 正確
`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	參數驗證失敗	確認參數格式正確

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`	400	source 或 target 為空字串	提供有效的語者 ID
`speaker_not_found`	404	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 皆已提供

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

Recording Entry 編輯 API（v1.4.0 新增）

針對歷史錄音，提供修正單句 STT 原文的 API。修正後可呼叫 GET /api/v1/sse/recordings/{taskId}/entries/{sid}/retranslate 自動重翻。完整規格見 reference/rest/entries.md。

PATCH /api/v1/tasks/{taskId}/entries/{sid}（修改單句原文）

功能說明

修改歷史錄音中單一句子的原文（original_text）。首次編輯時系統自動把 STT 原始輸出備份到 original_text_raw，並寫入 original_text_edited_at 與 transcript revision。只改原文不動翻譯——重翻請呼叫對應的 SSE 端點。

限制

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

認證方式

Header：X-API-Key

請求參數

參數	位置	類型	必填	說明
`taskId`	path	string	是	任務 ID（UUID，與舊命名 `recordingId` 為同一值）
`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	找不到 transcript blob

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

Summary Template API

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

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

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

功能說明

取得可用的摘要模板列表。每個模板代表不同的摘要風格，適用於不同場景（如會議、醫療諮詢、法律諮詢等）。

認證方式

Header：X-API-Key: YOUR_API_KEY

請求參數

參數	位置	類型	必填	預設	說明
`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}（取得單一摘要模板詳細內容）

曝露 IPEVO 內建模板的三層 Prompt 完整原始文字，供企業客戶整合時參考。完整 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`）

Generate Summary API（Bearer 認證）

對任意逐字稿文字（不限定來自 VAS 錄音）生成會議摘要，回應以 SSE 串流逐段送出。本端點獨立於錄音流程，可用於整合外部來源逐字稿。
若要對「已上傳到 VAS 的錄音」重新生成摘要，請改用 SSE 端點 GET / POST /api/v1/sse/regenerate/summary/{taskId}。
完整 schema 與 SSE 事件序列請參考 reference/rest/summary.md。

POST /api/v1/summary（對任意逐字稿生成摘要）

認證方式

⚠️ 與其他 REST 端點不同：此端點認證使用 Bearer Token（與其他 REST 端點的 X-API-Key 不同）：

Authorization: Bearer vas_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

請求參數（JSON Body）

欄位	類型	必填	限制 / 預設	說明
`content`	string	是	≤100,000 字元	摘要逐字稿內容
`mode`	string	是	enum `"builtin"` \| `"custom"`	顯式路徑選擇
`template`	string	builtin 必填 / custom 禁帶	exists prompt_templates.slug	內建模板 slug
`prompt`	string	custom 必填 / builtin 禁帶	≤2000 字元	客戶完整 prompt（取代 IPEVO 三層）
`prompt_slug`	string	custom 必填 / builtin 禁帶	≤64 字元、Unicode、禁控制字元	客戶自家識別碼（pass-through）
`format`	string	否	`bullet_points` / `paragraph` / `structured`（預設 `bullet_points`）	內建輸出格式
`language`	string	否	-	輸出語言代碼（如 `zh-TW`、`en-US`）
`plain_text`	bool	否	預設 `false`	要求純文字輸出（後端做 Markdown 後處理移除 `#` / `` / `*` / 列表符號）
`max_length`	int	否	-	摘要最大字數

互斥規則：違反 → 400 summary_mode_field_mismatch。

請求範例

# builtin mode（套 IPEVO 內建模板）
curl -N -X POST "https://vas-poc.vurbo.ai/api/v1/summary" \
  -H "Authorization: Bearer vas_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "...逐字稿...",
    "mode": "builtin",
    "template": "general",
    "language": "zh-TW",
    "plain_text": false
  }'

# custom mode（完整客製 prompt）
curl -N -X POST "https://vas-poc.vurbo.ai/api/v1/summary" \
  -H "Authorization: Bearer vas_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "...逐字稿...",
    "mode": "custom",
    "prompt": "你是會議記錄助手。請以條列方式列出討論的所有金額與承諾日期。",
    "prompt_slug": "client_x_finance_v3",
    "language": "zh-TW"
  }'

回應（SSE 串流）

事件序列依序為 start → chunk ×N → done（或 error）。done event 含 final_content / mode / template（effective slug）/ plain_text；custom mode 強制帶 prompt_snapshot（客戶 prompt 原樣 snapshot，是唯一重建依據）。完整 payload 請看 reference/rest/summary.md。

錯誤碼

錯誤碼	HTTP	說明
`auth_missing_token`	401	未提供 `Authorization` Header
`auth_invalid_api_key`	401	API Key 無效
`summary_text_empty`	400	`content` 為空
`summary_text_too_long`	400	`content` 超過 100,000 字元上限
`summary_invalid_mode`	400	`mode` 不是 `builtin` / `custom`
`summary_mode_field_mismatch`	400	mode 與欄位組合不符（必填缺漏 / 禁帶被帶入）
`summary_prompt_too_long`	400	`prompt` 超過 2000 字元
`summary_prompt_slug_too_long`	400	`prompt_slug` 超過 64 字元
`summary_prompt_slug_invalid`	400	`prompt_slug` 含控制字元（`\n` / `\r` / `\t` / `\0` 等）
`summary_generation_failed`	500	LLM 生成失敗（已 sanitize raw error）

錯誤處理

統一錯誤格式

所有 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.5.7 最後更新：2026-05-20

Languages

Sse Api