REST API

Summary

概述

對任意逐字稿文字生成會議摘要，回應以 SSE 串流逐段送出。本端點獨立於錄音流程，可用於整合外部來源的逐字稿（其他系統的會議紀錄、檔案上傳前預覽等）。

如果你要對「已上傳到 VAS 的錄音」重新生成摘要，請改用 GET / POST /api/v1/sse/regenerate/summary/{taskId}。

連線資訊

項目	值
端點	`POST /api/v1/summary`
基礎路徑	`https://vas-poc.vurbo.ai`
協定	HTTP + Server-Sent Events (SSE) 回應
認證方式	Header `Authorization: Bearer <api_key>`

注意：此端點認證方式為 Authorization: Bearer，與其他 REST 端點的 X-API-Key 不同。

請求

Request Body (JSON)

欄位	類型	必填	限制 / 預設	說明
`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`）	builtin 輸出格式（custom 下不適用）
`language`	string	否	-	輸出語言代碼（如 `zh-TW`、`en-US`）
`plain_text`	bool	否	預設 `false`	純文字輸出（後端做 Markdown 後處理移除 `#`/``/`*`/列表符號等）
`max_length`	int	否	-	摘要最大字數

互斥規則：

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

違反 → 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": "medical_consultation",
    "language": "zh-TW",
    "plain_text": true
  }'

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": "你是皮膚科專科助手。請從逐字稿萃取：1) 主訴 2) Fitzpatrick 分型 3) 過敏原史。輸出 JSON。",
    "prompt_slug": "skin-clinic-acme-v2",
    "language": "zh-TW",
    "plain_text": true
  }'

效果：

後端不查詢內建模板
客戶 prompt 取代內建模板規則，僅套上最小預設處理（語言、純文字、安全防護）
prompt 內容強制 snapshot 至 done event 並儲存於後端記錄（唯一重建依據）

SSE 事件

事件序列

1. start    → 開始生成
2. chunk    → 摘要片段（重複 N 次，含 markdown）
3. done     → 生成完成（含最終清洗後內容、custom mode 含 prompt_snapshot）
4. error    → 發生錯誤（替代 done）

`start` event

{
  "summary_id": "sum_abc123",
  "mode": "custom",
  "template": "skin-clinic-acme-v2",
  "format": "bullet_points",
  "language": "zh-TW",
  "plain_text": true
}

欄位	類型	說明
`summary_id`	string	此次摘要的內部 ID
`mode`	string	`"builtin"` 或 `"custom"`
`template`	string	effective slug — builtin → 內建 slug；custom → 客戶 slug（即 request 的 `prompt_slug`）
`format`	string	輸出格式
`language`	string	輸出語言
`plain_text`	bool	是否啟用純文字模式

`chunk` event

{ "content": "本次會議討論..." }

串流片段（含 markdown，前端可即時呈現）。

`done` event

{
  "summary_id": "sum_abc123",
  "tokens_used": { "input": 1234, "output": 567 },
  "created_at": "2026-05-13T08:30:00Z",
  "mode": "custom",
  "template": "skin-clinic-acme-v2",
  "plain_text": true,
  "final_content": "本次會議...（plain_text=true 時為清洗後純文字）",
  "prompt_snapshot": "你是皮膚科專科助手..."
}

欄位	類型	說明
`summary_id`	string	同 start
`tokens_used.input` / `.output`	int	Token 用量
`created_at`	string	ISO 8601 時戳
`mode`	string	同 start
`template`	string	effective slug
`plain_text`	bool	是否啟用純文字模式
`final_content`	string	完整內容（`plain_text=true` 時為清洗後純文字）
`prompt_snapshot`	string	僅 custom mode 出現，為客戶原樣傳入的 `prompt` 內容（強制 snapshot）

`error` event

{
  "errorCode": "summary_mode_field_mismatch",
  "message": "欄位與 mode 不符",
  "details": { "provider": "azure_openai" }
}

安全紀律：details 不包含 LLM 內部 raw error（避免曝露 prompt 片段、API key hash 等敏感資訊），僅標示 provider。完整錯誤訊息進 server log。

特有錯誤碼

錯誤碼	HTTP	說明	處理建議
`summary_text_empty`	400	`content` 為空字串	提供有效逐字稿
`summary_text_too_long`	400	`content` 超過 100,000 字元	縮短或拆分
`summary_invalid_mode`	400	`mode` 不是 `builtin` / `custom`	改為合法 mode
`summary_mode_field_mismatch`	400	mode 與欄位組合不符（必填缺漏或禁帶被帶入）	依 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_failed`	500	LLM 生成失敗	稍後重試
`summary_timeout`	504	生成逾時	稍後重試

整合最佳實踐

builtin path 先呼叫 GET /api/v1/summary-templates/{slug} 了解內建模板內容（見 summary-templates.md）
custom path 下 prompt 要自行包含輸出語言、結構描述、欄位要求（後端不再套用內建模板規則）
避免在 prompt 使用 markdown 符號（-、*、#）— 若 plain_text=true 後端後處理會把這些剝掉
不要把不可信的終端用戶輸入直接拼進 prompt（prompt injection 風險自負；後端已加 prompt injection 防護但非萬無一失）
不要在 prompt 寫密碼或 API Key（內容會送到 LLM 服務處理，且 custom mode 下會將 prompt 內容儲存於後端記錄供審計）
prompt_slug 命名建議帶版本（如 acme-v1 → acme-v2），供整合方追溯
plain_text=true 時預期輸出為完全純文字（連 - 列表符號都會被剝）；若需保留列表結構請使用 CJK 符號（・、①②③、【】）