浮動字幕 Token API

POST /api/v1/auth/tasks/{taskId}/subtitle-feed-token

功能說明

換取浮動字幕 feed 的短效存取 Token。浮動字幕 SSE（浮動字幕 SSE）以獨立、唯讀的連線訂閱進行中錄音的逐字稿；由於瀏覽器原生 EventSource 不支援自訂 HTTP Header，採用 Token 機制：先以 API Key 換取綁定該錄音的 feed_token，再以該 Token 連線 SSE。

認證方式

Header：X-API-Key（詳見 認證機制）。僅該錄音的擁有者可換取。

請求參數

請求範例

curl -X POST "https://vas-poc.vurbo.ai/api/v1/auth/tasks/3f9a.../subtitle-feed-token" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應

HTTP 200

{
  "token": "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdefghijkl",
  "expires_in": 900
}

回應欄位說明

Token 特性

競態處理

剛開始錄音時，後端可能尚未完成錄音建立。此時換取會回 425 Too Early，前端應短延遲後重試。

特有錯誤碼

注意：這三支端點的錯誤回應是 {"error": "<錯誤碼>"}，欄位名為 error，與其他端點的 data.error_code 不同。

觀眾分享

除錄音擁有者本人外，浮動字幕也可分享給現場其他觀眾共同觀看。擁有者開啟分享後取得一組分享密鑰（share secret），放入分享連結或 QR Code；觀眾以該密鑰換取唯讀的觀眾 Token，即可連線浮動字幕 SSE。

• 觀眾為唯讀，不需登入、不需 API Key，且不另計費。
• 同一場錄音的觀眾人數有上限（以伺服器設定為準，預設 10 人，不含擁有者本人）；目前人數與上限可由浮動字幕 SSE 的 viewers 事件取得（詳見 浮動字幕 SSE）。請以該事件的 max 欄位為準，勿寫死數值。
• 分享於錄音結束時自動失效。

POST /api/v1/auth/tasks/{taskId}/subtitle-share

開啟（或重置）觀眾分享，回傳分享密鑰。僅該錄音的擁有者可呼叫。

認證方式：Header X-API-Key。

成功回應（HTTP 200）

{
  "share_secret": "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdefghijkl",
  "expires_in": 43200
}

share_secret 僅在開啟當下回傳一次，請妥善保存於分享連結中。

DELETE /api/v1/auth/tasks/{taskId}/subtitle-share

停止分享，使分享連結失效。停止後不再放行新觀眾；既有觀眾連線最長於其 Token 有效期屆滿或錄音結束時結束。僅該錄音的擁有者可呼叫。

認證方式：Header X-API-Key。

成功回應（HTTP 200）

{ "revoked": true }

POST /api/v1/public/tasks/{taskId}/subtitle-feed-token

觀眾以分享密鑰換取唯讀的觀眾 Token，再以該 Token 連線浮動字幕 SSE。免登入、免 API Key。

請求範例

curl -X POST "https://vas-poc.vurbo.ai/api/v1/public/tasks/3f9a.../subtitle-feed-token" \
  -H "Content-Type: application/json" \
  -d '{"share_secret":"aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdefghijkl"}'

成功回應（HTTP 200）

{
  "token": "aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789abcdefghijkl",
  "expires_in": 900
}

回應欄位與上方擁有者 Token 相同；換得的 Token 同樣以 Query Parameter feed_token 連線浮動字幕 SSE。若觀眾人數已達上限，連線時會回 429（詳見 浮動字幕 SSE）。

頻率限制

• 同一場錄音每分鐘最多 30 次（所有觀眾合計，含分享連結無效的請求）。
• 超過限制時回 HTTP 429，並帶 Retry-After 標頭（需要等待的秒數）。這個錯誤採用一般錯誤格式（data.error_code 為 too_many_requests），與本端點其他錯誤的 {"error": ...} 格式不同。

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