重新生成摘要 SSE

連線資訊

注意：瀏覽器原生 EventSource API 不支援自訂 Header，需使用 fetch API 搭配 ReadableStream，或使用支援 Header 的 SSE 客戶端套件。

端點總覽

拆成預覽 / 存檔兩個端點：

已知限制：GET 預覽仍會計費 — LLM 真實消耗 token，不能讓 GET 端點白嫖。重複呼叫 GET 會重複計費，但不會改變後端儲存狀態。

共用：請求參數

GET 走 query string、POST 走 JSON body，欄位名與型別相同：

互斥規則：

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

違反 → 參數驗證失敗（error 事件，data 只有 message、不含 error_code）

GET /api/v1/sse/regenerate/summary/{taskId}（預覽）

功能說明

跑一次 LLM 重新生成摘要，僅串流回客戶端，不保存結果、不更新逐字稿記錄。

適用情境：客戶端想嘗試不同 prompt / 不同 plain_text 設定，比較結果後再決定是否存檔。

請求範例

builtin mode

curl -N "https://vas-poc.vurbo.ai/api/v1/sse/regenerate/summary/550e8400-e29b-41d4-a716-446655440000?mode=builtin&template=meeting&language=zh-TW&plainText=true" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

custom mode

curl -N "https://vas-poc.vurbo.ai/api/v1/sse/regenerate/summary/550e8400-e29b-41d4-a716-446655440000?mode=custom&prompt=%E8%AB%8B%E5%BC%B7%E8%AA%BFKPI&promptSlug=acme-meeting-v2&plainText=true" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

副作用

• 會產生一筆摘要計費（LLM 真實消耗 token）
• 不會更新 recordings.summary_mode / summary_template / summary_prompt_slug 三欄
• 不會覆寫已儲存的摘要

POST /api/v1/sse/regenerate/summary/{taskId}（存檔）

功能說明

GET 預覽的所有動作 + 寫入 DB 與逐字稿記錄。

請求範例

builtin mode

curl -N -X POST "https://vas-poc.vurbo.ai/api/v1/sse/regenerate/summary/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "builtin",
    "template": "meeting",
    "language": "zh-TW",
    "plainText": true
  }'

custom mode

curl -N -X POST "https://vas-poc.vurbo.ai/api/v1/sse/regenerate/summary/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: vas_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "custom",
    "prompt": "你是皮膚科專科助手。請從逐字稿萃取 Fitzpatrick 分型...",
    "promptSlug": "skin-clinic-acme-v2",
    "language": "zh-TW",
    "plainText": true
  }'

副作用

• 會產生一筆摘要計費
• 依 mode 互斥寫入 recordings 三欄：
  • builtin → summary_mode='builtin'、summary_template=<slug>、summary_prompt_slug=NULL
  • custom → summary_mode='custom'、summary_template=NULL、summary_prompt_slug=<客戶 slug>
• 更新任務的摘要語言：任務列表與歷史紀錄 init_metadata 的 summary_language 會隨之改為本次使用的語言
• 更新逐字稿記錄的 top-level 欄位並 revision += 1：
  • summary（純字串）、summary_language、summary_mode、summary_template（effective slug）、summary_plain_text
  • custom mode 強制 summary_prompt_snapshot（客戶 prompt 原樣 snapshot，是唯一重建依據）

事件序列（兩端點相同）

1. connected              → 連線確認
2. summary_regeneration   → 發送摘要片段（重複 N 次，累積式）
3. done                   → 生成完成
   或
3. error                  → 生成失敗（sse_summary_regeneration_failed，兩個端點都可能出現；
                            不儲存、不計費，**不會**送出 done）
   或
3. error                  → 儲存失敗或同時有其他寫入（storage_upload_failed／
                            transcript_revision_conflict，流程中止、**不會**送出 done）

儲存失敗或同時有其他寫入的 error 只會出現在儲存端點（POST）。預覽端點（GET）不寫入逐字稿，不會走到這條分支。

connected

{
  "message": "Summary regeneration stream connected (taskId: 550e8400-..., mode: custom, endpoint: preview)"
}

注意：避免混淆：message 中的 mode 是摘要模式（builtin / custom，即 request 帶入的 mode）；endpoint 才是端點模式（preview GET / persist POST）。兩者語義不同，請勿混為一談。

summary_regeneration

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

done

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "tokens_used": 123,
  "final_content": "本次會議...（清洗後完整內容）",
  "mode": "custom",
  "template": "skin-clinic-acme-v2",
  "plain_text": true,
  "persisted": true,
  "summary_language": "zh-TW",
  "characters_billed": 12700,
  "charged": "1.3",
  "billed": true,
  "prompt_snapshot": "你是皮膚科專科助手..."
}

計費欄位：characters_billed、charged、billed 三欄僅在本次實際產生消耗時出現。 未產生消耗時（例如生成失敗）三欄皆不出現。判斷是否計費請以 billed 為準 （billed 為 true 才是計費）——此判準適用所有帶計費欄位的端點，不需為個別端點寫例外。 代呼叫並向終端用戶計價的整合方，可直接採用 charged 而不必自行推算。 預覽（GET）與儲存（POST）都會計費，兩者的 done 皆帶計費欄位。 生成失敗（sse_summary_regeneration_failed），或儲存端點因儲存失敗而送出 error（見「事件序列」第 3 步），該次不計費、也不會有 done。

特有錯誤碼

參數驗證失敗沒有錯誤碼。 mode 不合法、欄位組合不符、prompt 或 promptSlug 超長／含控制字元等，都在參數驗證階段被擋下，回應是 error 事件但 data 只有 message 一欄、不含 error_code。請以 message 呈現給使用者，不要嘗試比對錯誤碼。

template 的 slug 不存在也屬於參數驗證失敗（message 為 The specified summary template does not exist），不會回 422、也沒有錯誤碼。

內容過濾 — SSE 端的當前狀態：

即時錄音摘要與檔案匯入摘要已支援內容過濾自動降級（標準模式 → 中性模式 → 段落省略模式），被擋時會自動產出簡化摘要。但本端點（SSE regenerate/summary）尚未支援——觸發內容過濾時本端點一律回 sse_summary_regeneration_failed，回應不會區分「被過濾」與其他生成失敗。

後續版本將支援自動降級，並於 done event 擴充 fallback_level / dropped_segments 欄位。在此之前，若重試仍失敗，請調整 prompt 或逐字稿內容。

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