SSE API

Ad-hoc 摘要 SSE

連線資訊

項目	值
基礎路徑	`https://vas-poc.vurbo.ai/api/v1/sse`
協定	HTTP + Server-Sent Events (SSE)
資料格式	text/event-stream
認證方式	Header `X-API-Key: {KEY}`（本端點不接受 query string 帶金鑰）

注意：本端點僅接受 POST（JSON body），瀏覽器原生 EventSource API 無法使用；請以 fetch API 搭配 ReadableStream，或任何支援讀取串流回應的 HTTP 客戶端呼叫。

端點總覽

方法	端點	是否保存結果	計費	用途
POST	`/api/v1/sse/summary`	否	是	對請求自帶的任意文字內容生成摘要（不綁定任何錄音）

與重新生成摘要的差異：重新生成一律以服務端保存的逐字稿為輸入；本端點以請求帶入的 content 為輸入，適用於「多段錄音合併後的完整逐字稿」「使用者編輯後的逐字稿」等服務端沒有的內容。生成結果不會儲存，僅串流回客戶端。

v1.9.1 新增。早期版本曾有過另一個同路徑端點（V1.8.0 移除），本端點為全新契約——認證、計費與重複請求規則皆不同，請勿沿用舊整合程式。

請求參數（JSON body）

參數	類型	必填	限制	說明
`content`	string	是	≤200,000 字元	要摘要的完整文字內容
`idempotency_key`	string	是	≤64 字元、`A-Z a-z 0-9 . _ -`	重複請求識別碼，用於避免重複扣點（詳見下方「重複請求與計費保證」）
`mode`	string	是	`"builtin"` \| `"custom"`	摘要模式：內建模板或自訂 prompt
`template`	string	builtin 必填 / custom 禁帶	有效的內建模板 slug	內建模板 slug
`prompt`	string	custom 必填 / builtin 禁帶	≤3000 字元	客戶完整 prompt
`promptSlug`	string	custom 必填 / builtin 禁帶	≤64 字元、Unicode、禁控制字元	客戶自訂識別碼（原樣回傳，不另做處理）
`language`	string	否	-	摘要輸出語言代碼（如 `zh-TW`、`en-US`），未指定時預設 `zh-TW`
`plainText`	boolean	否	預設 false	要求純文字輸出（自動移除 Markdown 格式符號）

互斥規則（與重新生成摘要相同）：

mode=builtin 下不可帶 prompt 或 promptSlug
mode=custom 下不可帶 template，但 prompt 與 promptSlug 必填

錯誤回應模式（與其他 SSE 端點不同，請注意）

本端點供後端系統整合使用，串流開始前的錯誤一律回真實 HTTP 狀態碼（JSON body），不採其他 SSE 端點「HTTP 200 + error 事件」的慣例：

階段	回應形式
認證失敗（401/403）、參數驗證失敗（422）、模板不存在或停用（404）、內容全為空白（400）、點數不足（402）、重複請求識別碼衝突（409）、超過頻率限制（429）	真實 HTTP 狀態碼 + JSON 錯誤 body
串流開始後（生成失敗、內容被過濾等）	HTTP 200 + SSE `error` 事件

認證僅接受 Header X-API-Key，不接受 query string 帶金鑰。

422 的 JSON body 在 data.details.errors 帶各欄位的錯誤訊息，方便程式判斷：

{
  "type": "error",
  "data": {
    "error_code": "validation_failed",
    "message": "Validation failed",
    "details": { "errors": { "content": ["The content parameter is required"] } }
  }
}

計費

依 content 的字元數計費：0.1 點 / 每 1,000 字元（未滿 1,000 進位；與會議摘要、重新生成摘要相同費率）。
生成成功才計費；生成失敗（含內容被過濾、串流中途停住或沒有正常結束）不計費。摘要不完整而 done 帶 truncated 時仍算成功，照常計費。
例：35,000 字元的 content ＝ 3.5 點；1 字元＝ 0.1 點（最低計費單位）。

重複請求與計費保證

idempotency_key 由客戶端提供（建議使用你方系統的合併批次 ID、版本 ID 等穩定識別碼）。系統以整份請求內容——content 與所有摘要參數（mode / template / prompt / promptSlug / language / plainText）——判斷兩次請求是否為同一次工作的重試：

情境	行為
同一識別碼＋完全相同的請求重試	不重複計費，但會重新生成（結果可能與上次不同，不會重播上次結果）；即使帳戶點數已用完仍可重試（原請求已計費）
同一識別碼＋任一欄位不同（`content` 或任一摘要參數）	回 409 `summary_idempotency_key_conflict`，不生成、不計費
首次請求生成失敗後重試	失敗不佔用識別碼——重試（即使更換內容）視為全新請求，正常計費

重試必須帶與原請求完全相同的欄位；要換內容或換 prompt 生成新摘要時，請帶新的 idempotency_key。
idempotency_key 只在同一把 API Key 內有效：不同 API Key 帶同一個識別碼互不相干、各自計費。用備用金鑰重送同一筆工作會被計為兩次請求。
邊界情況：若同一個識別碼被同時用於兩個不同的請求（客戶端錯誤），先完成者取得該識別碼；後者仍會正常計費並交付結果，但之後以該識別碼重試（無論內容）會得到 409，請改用新的識別碼。

請求範例

builtin mode

curl -N -X POST "https://vas-poc.vurbo.ai/api/v1/sse/summary" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "（多段錄音合併後的完整逐字稿…）",
    "idempotency_key": "merge-batch-20260813-001",
    "mode": "builtin",
    "template": "meeting",
    "language": "zh-TW",
    "plainText": true
  }'

custom mode

curl -N -X POST "https://vas-poc.vurbo.ai/api/v1/sse/summary" \
  -H "X-API-Key: vas_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "（使用者編輯後的完整逐字稿…）",
    "idempotency_key": "revision-8f31c2",
    "mode": "custom",
    "prompt": "請從逐字稿萃取決議事項與待辦…",
    "promptSlug": "acme-meeting-v2",
    "language": "zh-TW"
  }'

事件序列

1. connected              → 連線確認
2. summary_regeneration   → 發送摘要片段（重複 N 次，累積式）
3. done                   → 生成完成
   或
3. error                  → 生成失敗（sse_summary_regeneration_failed），不會送出 done、不計費

connected

{ "message": "Ad-hoc summary stream connected (mode: builtin)" }

summary_regeneration

{ "text": "本次會議討論了以下議題：\n1. 產品開發進度", "is_final": false }

欄位	類型	說明
`text`	string	累積的摘要內容（plainText=true 時 `is_final=true` 的 text 為清洗後純文字）
`is_final`	boolean	是否為最終結果

done

{
  "tokens_used": 123,
  "final_content": "本次會議...（完整摘要內容）",
  "mode": "custom",
  "template": "acme-meeting-v2",
  "plain_text": true,
  "characters_billed": 35000,
  "charged": "3.5",
  "idempotency_key": "revision-8f31c2",
  "billed": true,
  "summary_language": "zh-TW",
  "prompt_snapshot": "請從逐字稿萃取決議事項與待辦…"
}

欄位	類型	說明
`tokens_used`	number	總 token 用量
`final_content`	string	完整摘要內容（`plainText=true` 時為清洗後純文字）
`mode`	string	摘要模式：`"builtin"` 或 `"custom"`
`template`	string	實際生效的識別碼 — builtin → 內建模板 slug；custom → 客戶自訂識別碼
`plain_text`	boolean	是否啟用純文字模式
`characters_billed`	number	本次計費依據（`content` 的字元數）
`charged`	string	本次操作依費率計算的消耗點數。此值反映用量：吃到飽方案已涵蓋的用量，此欄位仍回報消耗量
`idempotency_key`	string	請求帶入的冪等鍵原樣回顯（供對帳／關聯）
`billed`	boolean	本次請求是否實際扣點——重試（免費）與生成結果為空時為 `false`。對帳請以此欄為準，不要直接加總 `characters_billed`
`summary_language`	string	本次摘要實際使用的語言（BCP 47）。有帶 `language` 時為該值，未帶時為 `zh-TW`（`language` 的預設值）。免費重試與生成結果為空時也會帶，一定有值（v1.16.5 新增）
`prompt_snapshot`	string	僅 custom mode 出現，為客戶原樣傳入的 `prompt` 內容
`truncated`	boolean	僅在摘要未能完整產出時出現（值恆為 `true`）。摘要完整時此欄位完全不存在。出現時代表 `final_content` 並非完整的摘要：摘要長度達到輸出上限，或生成時間達到處理時間上限（只回傳已完成的部分）。兩者都照常計費。可提示使用者，或改用較精簡的摘要模板重新生成

與重新生成摘要的 done 差異：本端點沒有 task_id（不綁定錄音）與 persisted（永不儲存），另多出 idempotency_key 一欄。
計費欄位 characters_billed / charged 的語意與重新生成摘要一致；差別在本端點的 characters_billed 與 charged 恆會出現（必定算得出來），而 billed 在免費重試與生成結果為空時為 false。對帳請以 billed 為準。

特有錯誤碼

串流開始前（真實 HTTP 狀態碼 + JSON）：

錯誤碼	HTTP	說明	處理建議
`validation_failed`	422	參數驗證失敗（缺欄位、超過長度上限、mode 欄位組合不符等）	依 `data.details.errors` 修正欄位
`summary_idempotency_key_conflict`	409	同一 `idempotency_key` 已用於不同的請求內容（`content` 或任一摘要參數不同）	換新的 `idempotency_key`；重試請帶與原請求完全相同的欄位
`sse_template_not_found`	404	找不到摘要模板（builtin mode，模板不存在或已停用）	確認 `template` 正確
`summary_text_empty`	400	`content` 沒有可摘要內容（全為空白字元）	提供有效內容
`stt_quota_exceeded`	402	可用點數不足以支付本次應計點數	儲值後重試
`too_many_requests`	429	同一個 `idempotency_key` 的免費重新生成次數已達上限	免費重試是給「已扣款但交付失敗」用的，次數有限、以 24 小時為窗口。要立即重新生成請改用新的 `idempotency_key`（會重新計費）。注意：此狀態不會在數秒內解除，收到後不要進入短間隔重試迴圈

串流開始後（HTTP 200 + SSE error 事件）：

錯誤碼	說明	處理建議
`sse_summary_regeneration_failed`	生成失敗（含內容被 LLM 服務過濾、串流中途停住或沒有正常結束；回應不含內部錯誤細節）。之前收到的 `summary_regeneration` 片段不是完整結果，請捨棄	稍後重試；內容被過濾時請調整內容或 prompt。失敗不計費、不佔用識別碼

版本：V1.24.1 最後更新：2026-09-28

觀眾端 API

音訊串流