REST API

音檔匯入 API

端點總覽

方法	端點	說明
POST	`/api/v1/imports/check-quota`	檢查點數
POST	`/api/v1/imports`	上傳音檔
GET	`/api/v1/imports/{importId}`	查詢匯入狀態
GET	`/api/v1/imports`	取得匯入列表

POST /api/v1/imports/check-quota

功能說明

檢查使用者點數是否足夠上傳指定時長的音檔。建議在上傳前先呼叫此 API 進行預檢查，避免上傳大檔案後才發現點數不足。

請求參數

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

成功回應

HTTP 200

{
  "data": {
    "allowed": true,
    "reason": null,
    "is_unlimited": false,
    "remain_quota": 480.0,
    "duration_minutes": 60,
    "estimated_points": 60.0
  }
}

回應欄位說明

欄位	類型	說明
`data.allowed`	boolean	是否允許上傳（點數足夠或方案允許時為 `true`）
`data.reason`	string \| null	不允許的原因：`null`（通過）／`insufficient_credit`（點數不足，儲值可解）／`plan_not_allowed`（方案不含匯入，需升級方案）／`plan_daily_limit_reached`（今日方案用量已滿，明日重置；儲值無法解決，v1.16.4 新增）
`data.is_unlimited`	boolean	是否為吃到飽（不限點數）
`data.remain_quota`	float \| null	剩餘點數；吃到飽時為 `null`
`data.duration_minutes`	integer	音檔預估時長（分鐘，無條件進位）
`data.estimated_points`	float	預估扣點（以 STT 基準估算；實際扣點另含翻譯／語者等功能，於上傳時精算）

remain_quota 語意變更（v1.9.0）：對「被分配專屬額度」的 API Key，回傳該把 key 實際可動用的額度（專屬額度，而非帳戶總餘額）；未分配專屬額度的帳號數值不變。

特有錯誤碼

此端點無特有錯誤碼，僅可能回傳通用認證錯誤 —— 被擋下的情況一律回 HTTP 200 ＋ allowed: false ＋ reason。

預檢的 `reason`	實際上傳會收到
`plan_not_allowed`	403 `plan_feature_not_allowed`
`insufficient_credit`	402 `stt_quota_exceeded`
`plan_daily_limit_reached`	402 `plan_daily_limit_reached`（刻意同名同字，可 1:1 對應）

注意：預檢是預測，不是保證。 回 allowed: true 之後、實際上傳之前，其他上傳或進行中錄音的每分鐘結算仍可能把額度用掉，屆時上傳照樣會被擋。

POST /api/v1/imports

功能說明

上傳音檔進行語音辨識與翻譯處理。上傳成功後會在背景處理，可透過查詢匯入狀態 API 追蹤進度。

請求參數（multipart/form-data）

參數	類型	必填	說明
`file`	file	是	音檔（mp3/wav/m4a，最大 500MB）。格式依檔案實際內容判斷，副檔名與內容不符時（例如檔名是 `.mp3`、內容是 WAV）依內容處理
`transcription_languages`	string	是	轉錄語言（JSON 陣列字串，如 `'["zh-TW"]'`）。最多 10 種、不可重複
`translation_languages`	string	否	翻譯語言（JSON 陣列字串，如 `'["en-US"]'`）。最多 12 種、不可重複
`recognition_mode`	string	是	辨識模式：`single`（單人）/ `multi_speaker`（多人）。帶 `multi_language` 或 `multi_channel` 會回 422 `import_recognition_mode_unsupported`
`summary_template`	string	否	摘要模板識別碼（最大 50 字元，須為已啟用的 `summary` 類別 slug）
`summary_mode`	string	否	摘要模式：`builtin`（預設，走 `summary_template`）或 `custom`（走 `summary_prompt`）。未指定＝沿用 `summary_template`
`summary_prompt`	string	否	`custom` 模式的自訂 prompt 全文（最大 3000 字元，完整取代內建模板）。`custom` 必填、其他模式禁帶
`summary_prompt_slug`	string	否	`custom` 模式的自訂識別碼（最大 64 字元，pass-through 不校驗）。`custom` 必填、其他模式禁帶
`terminology`	string	否	術語庫（JSON 物件字串，格式見下方）
`fuzzy_correction`	string	否	模糊詞校正規則（JSON 物件字串，格式見下方）
`translation_dict`	string	否	翻譯字典（JSON 物件字串，格式見下方）
`callback_url`	string	否	Webhook 回呼 URL（處理完成/失敗時通知，最大 2048 字元）

Webhook 通知：設定 callback_url 後，匯入完成時會收到 import.completed 事件，失敗時會收到 import.failed 事件。詳見 Webhook 指南。

文字處理參數格式

術語庫 (terminology)：提升特定詞彙的辨識準確度

{
  "zh-TW": [
    { "term": "語者分離" },
    { "term": "即時轉錄" }
  ]
}

以語言代碼為 key，術語陣列為 value
term：術語文字（必填，最大 100 字元）
每種語言最多 500 個術語，且所有語言合計也不得超過 500 筆
模糊詞校正每種語言最多 4000 條規則，且所有語言合計也不得超過 4000 條

以上數字是預設值：實際生效的上限可依環境調整，一律以 422 回應裡的訊息為準。

注意：兩個上限都會驗證，超過任一個都會回 422 並指出實際筆數。多語言字庫請以合計為準規劃。

模糊詞校正 (fuzzy_correction)：修正讀音與術語不同的錯字

通常不需手動設定 —— 讀音相同的錯字由 terminology 直接涵蓋，僅在錯字與正確詞讀音不同時需要。

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

以語言代碼為 key，校正規則陣列為 value
correct：正確詞彙（必填，最大 200 字元）
incorrect：錯誤變體列表（條件必填，每項最大 200 字元）

只給正確詞、不列錯字：correct 是中文（含漢字）時，incorrect 可以整個省略 —— 系統會依讀音自動比對，逐字稿中讀音相同或相近的寫法會被修正回 correct。
{ "fuzzy_correction": { "zh-TW": [{ "correct": "艾思通" }] } }
上例不必列出任何錯字，「愛思通」「愛時通」「愛司東」「愛似通」都會被修正。只有讀音差距較大的寫法（例如「愛自動」）或音節數不同的（例如「愛松」）才需要另外列進 incorrect。
注意：兩個條件缺一不可：語言要是中文（zh-TW / zh-CN / zh-HK 等），且 correct 要含漢字。不滿足時 incorrect 仍為必填 —— 因為那些情況省略了不會有任何效果，收下反而會讓你以為設定成功。日文、韓文、英文的錯字請明確列出。

case_insensitive：本條規則的變體是否忽略大小寫（選填，預設 false = 嚴格比對）

大小寫：case_insensitive 為選填、預設 false（嚴格比對）。設為 true 時，該條規則的所有 incorrect 變體都會忽略大小寫。旗標是逐條的 —— 同一個 correct 可拆成多條規則各自設定，例如把不會與一般詞彙衝突的變體設為忽略大小寫、把可能撞到人名的變體維持嚴格。對中文規則無作用（中文無大小寫概念）。

同一個錯誤變體出現在多條規則時：碰撞以 incorrect（錯誤變體）為準，不是 correct。大小寫旗標取嚴格優先（任一條沒開 case_insensitive，該變體即以嚴格比對處理）。因此把同一個 correct 拆成多條規則是安全的，只要各條的 incorrect 不重複。
注意：開啟後誤傷面會擴大：若 ivo 設為忽略大小寫，人名 Ivo 也會被替換。

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

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

頂層鍵：目標語言代碼
source：原文詞彙（必填，最大 200 字元）
target：該語言的指定譯法（必填，最大 200 字元）
case_sensitive：是否只在大小寫完全相符時才套用（選填，預設 false = 不分大小寫）
每個語言最多 3000 個條目

舊格式仍然支援：先前的條目陣列格式繼續接受，內容與行為完全不變。

大小寫旗標對照：fuzzy_correction 與 translation_dict 的大小寫開關欄位名互為反義、預設值代表的行為也相反——
區塊欄位預設值預設行為
fuzzy_correction case_insensitive false 嚴格（區分大小寫）
translation_dict case_sensitive false 寬鬆（不分大小寫）
兩者都預設 false，但一個代表嚴格、另一個代表寬鬆。請勿共用同一個變數或直接鏡射——設錯不會有任何錯誤訊息，只會做出與預期相反的比對行為。

區塊	欄位	預設值	預設行為
`fuzzy_correction`	`case_insensitive`	`false`	嚴格（區分大小寫）
`translation_dict`	`case_sensitive`	`false`	寬鬆（不分大小寫）

請求範例

基本請求

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": "語者分離"}]}' \
  -F 'fuzzy_correction={"zh-TW": [{"correct": "語者分離", "incorrect": ["語這分離"]}]}' \
  -F 'translation_dict={"en-US": [{"source": "語者分離", "target": "Speaker Diarization"}]}'

含 Webhook 回呼的請求

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 "callback_url=https://your-server.com/webhooks/vas"

成功回應

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": "660f9500-f30c-52e5-b827-557766550000",
    "error_code": null,
    "error_message": null,
    "created_at": "2026-02-23T10:00:00.000Z",
    "updated_at": "2026-02-23T10:00:00.000Z",
    "downgraded_features": []
  }
}

回應欄位說明

欄位	類型	說明
`data.import_id`	string	匯入 ID（UUID）
`data.status`	string	狀態：`pending`
`data.stage`	string \| null	處理階段（初始為 `null`）
`data.progress`	integer	進度百分比（初始為 `0`）
`data.message`	string \| null	處理訊息
`data.original_filename`	string	原始檔案名稱
`data.file_size`	string	檔案大小（格式化）
`data.task_id`	string	任務 ID（上傳成功即有值，可立即用於導向該筆任務）
`data.error_code`	string \| null	錯誤碼（失敗時才有值）
`data.error_message`	string \| null	錯誤訊息（失敗時才有值）
`data.created_at`	string	建立時間（ISO 8601）
`data.updated_at`	string	最後更新時間（ISO 8601）
`data.downgraded_features`	array	被降級略過的子功能列表（v1.9.0）：吃到飽方案含匯入、但不含部分子功能（如語者分離 `speaker_diarization`、翻譯 `translation`）時，該子功能會被略過、匯入照常進行；空陣列＝無降級

特有錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`import_file_too_large`	413	檔案大小超過 500MB 限制	壓縮或分割檔案
`import_invalid_format`	415	不支援的音檔格式	使用 mp3/wav/m4a 格式
`import_recognition_mode_unsupported`	422	匯入不支援此辨識模式（`multi_language`、`multi_channel`）。`data.details` 帶 `field: "recognition_mode"` 與 `supportedModes: ["single", "multi_speaker"]`	改用 `single` 或 `multi_speaker`
`stt_quota_exceeded`	402	可用點數不足以支付本次匯入的預估點數	儲值後再上傳
`plan_feature_not_allowed`	403	吃到飽方案不含檔案匯入	升級方案；可用 `GET /api/v1/me/plan` 查方案內容
`plan_daily_limit_reached`	402	已達方案每日用量上限	依方案規則重置（隔日）後再上傳

GET /api/v1/imports/{importId}

功能說明

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

匯入產生的任務被刪除後，對應的匯入紀錄會一併移除，查詢會回 404 import_not_found。

請求參數

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

成功回應

HTTP 200

{
  "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": "660f9500-f30c-52e5-b827-557766550000",
    "error_code": null,
    "error_message": null,
    "created_at": "2026-02-23T10:00:00.000Z",
    "updated_at": "2026-02-23T10:05:00.000Z"
  }
}

欄位	類型	說明
`data.status`	string	狀態：`pending` / `processing` / `completed` / `failed`
`data.stage`	string \| null	處理階段：`converting` / `transcribing` / `translating` / `summarizing`
`data.progress`	integer	進度百分比（0-100）
`data.task_id`	string \| null	任務 ID（可用於 Tasks API）。自上傳成功起即有值，不需等到處理完成
`data.error_code`	string \| null	失敗時的錯誤碼
`data.error_message`	string \| null	失敗時的錯誤訊息（一般說明，不含內部細節）

status 狀態流轉

pending → processing → completed
                    → failed

completed 與 failed 是最終狀態，之後不會再改變：已標為 failed 的匯入不會再變成 completed，也不會扣點。
處理中遇到暫時性的錯誤會自動重試，重試期間維持 processing；重試用盡才標為 failed，import.failed Webhook 只會送出一次。
長時間沒有開始處理的匯入（停在 pending）會標為 failed，error_code 為 PROCESSING_TIMEOUT。
error_message 是依錯誤碼提供的一般說明，不含內部細節；需要排查時請提供 import_id。錯誤碼一覽見錯誤碼參考。

stage 處理階段

階段	說明
`converting`	音檔格式轉換中
`transcribing`	語音辨識中
`translating`	翻譯處理中
`summarizing`	摘要生成中

當音檔因靜音、音量過小、雜訊或辨識語言與音檔不符而辨識不出任何語音內容時，系統仍會以 completed 結束（不是 failed），task_id 正常產出，但對應任務的逐字稿 entries 為空陣列。客戶端應透過 GET /api/v1/sse/history/transcribe/{taskId} 載入後再依句子數判斷是否顯示空狀態。詳見音檔匯入指南 – 音檔無法辨識時的行為。

特有錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`import_not_found`	404	找不到匯入任務	確認 importId 正確；匯入產生的任務若已刪除，匯入紀錄也會一併移除

GET /api/v1/imports

功能說明

取得使用者的匯入任務列表（分頁）。已刪除任務所對應的匯入紀錄不會出現在列表中。

認證方式

Header：X-API-Key（詳見認證機制）

請求參數

參數	位置	類型	必填	說明
`per_page`	query	integer	否	每頁筆數（預設 20）

請求範例

curl -X GET "https://vas-poc.vurbo.ai/api/v1/imports?per_page=20" \
  -H "X-API-Key: vas_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW"

成功回應

HTTP 200

{
  "data": [
    {
      "import_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "stage": null,
      "progress": 100,
      "message": null,
      "original_filename": "meeting.mp3",
      "file_size": "15.2 MB",
      "task_id": "660f9500-f30c-52e5-b827-557766550000",
      "error_code": null,
      "error_message": null,
      "created_at": "2026-02-23T10:00:00.000Z",
      "updated_at": "2026-02-23T10:15:00.000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 20,
    "total": 55
  }
}

回應欄位說明

欄位	類型	說明
`data`	array	匯入任務列表（各欄位同查詢匯入狀態回應）
`meta.current_page`	integer	目前頁碼
`meta.last_page`	integer	最後一頁頁碼
`meta.per_page`	integer	每頁筆數
`meta.total`	integer	總筆數

特有錯誤碼

此端點無特有錯誤碼，僅可能回傳通用認證錯誤。

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

字庫驗證 API

金鑰自助查詢 API

用這把 API Key 查詢它自己的點數批次、用量紀錄與設定（V1.21.0 新增）。