REST API
Imports
端點總覽
| 方法 | 端點 | 說明 |
|---|---|---|
| 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 進行預檢查，避免上傳大檔案後才發現預算不足。
認證方式
Header：X-API-Key（詳見 認證機制）
請求參數
| 參數 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
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,
"remaining_budget": 48.48,
"is_unlimited": false,
"duration_minutes": 25,
"estimated_cost": 0.4236,
"remaining_minutes": 2864
}
}
回應欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
data.allowed | boolean | 是否允許上傳（預算未超額時為 true） |
data.remaining_budget | float | null | 剩餘月度預算（USD），無預算限制時為 null |
data.is_unlimited | boolean | 是否為無預算限制 |
data.duration_minutes | integer | 音檔預估時長（分鐘，無條件進位） |
data.estimated_cost | float | 預估 STT 處理費用（USD） |
data.remaining_minutes | integer | null | 剩餘預算可用的等效 STT 分鐘數，無預算限制時為 null |
特有錯誤碼
此端點無特有錯誤碼，僅可能回傳通用認證錯誤。
POST /api/v1/imports
功能說明
上傳音檔進行語音辨識與翻譯處理。上傳成功後會在背景處理，可透過 查詢匯入狀態 API 追蹤進度。
認證方式
Header：X-API-Key（詳見 認證機制）
請求參數（multipart/form-data）
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
file | file | 是 | 音檔（mp3/wav/m4a，最大 500MB） |
transcription_languages | string | 是 | 轉錄語言（JSON 陣列字串，如 '["zh-TW"]'） |
translation_languages | string | 否 | 翻譯語言（JSON 陣列字串，如 '["en-US"]'） |
recognition_mode | string | 是 | 辨識模式：single（單人）/ multi_speaker（多人） |
summary_template | string | 否 | 摘要模板識別碼（最大 50 字元，須為已啟用的 summary 類別 slug） |
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": "語者分離", "boost": 1.5 },
{ "term": "即時轉錄", "boost": 1.5 }
]
}
- 以語言代碼為 key，術語陣列為 value
term：術語文字（必填，最大 100 字元）boost：權重（選填，預設 1.0）- 每種語言最多 500 個術語
模糊詞校正 (fuzzy_correction)：自動修正常見的辨識錯誤
{
"zh-TW": [
{ "correct": "語者分離", "incorrect": ["語這分離", "語者分力"] }
]
}
- 以語言代碼為 key，校正規則陣列為 value
correct：正確詞彙（必填，最大 200 字元）incorrect：錯誤變體列表（必填，每項最大 200 字元）
翻譯字典 (translation_dict)：指定專有名詞的翻譯方式
[
{ "source": "語者分離", "translations": { "en-US": "Speaker Diarization" } }
]
source：原文詞彙（必填，最大 200 字元）translations：各語言對應翻譯（以語言代碼為 key，每項翻譯文字最大 200 字元）- 最多 50 個條目
請求範例
基本請求
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": "語者分離", "boost": 1.5}]}' \
-F 'fuzzy_correction={"zh-TW": [{"correct": "語者分離", "incorrect": ["語這分離"]}]}' \
-F 'translation_dict=[{"source": "語者分離", "translations": {"en-US": "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": null,
"error_code": null,
"error_message": null,
"created_at": "2026-02-23T10:00:00.000Z",
"updated_at": "2026-02-23T10:00:00.000Z"
}
}
回應欄位說明
| 欄位 | 類型 | 說明 |
|---|---|---|
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 | null | 任務 ID（處理完成後才有值） |
data.error_code | string | null | 錯誤碼（失敗時才有值） |
data.error_message | string | null | 錯誤訊息（失敗時才有值） |
data.created_at | string | 建立時間（ISO 8601） |
data.updated_at | string | 最後更新時間（ISO 8601） |
特有錯誤碼
| 錯誤碼 | HTTP 狀態碼 | 說明 | 處理建議 |
|---|---|---|---|
import_file_too_large | 413 | 檔案大小超過 500MB 限制 | 壓縮或分割檔案 |
import_invalid_format | 415 | 不支援的音檔格式 | 使用 mp3/wav/m4a 格式 |
stt_quota_exceeded | 402 | STT 配額已超限 | 等待下月配額重置或調整方案 |
GET /api/v1/imports/{importId}
功能說明
查詢指定匯入任務的處理狀態與進度。
認證方式
Header：X-API-Key（詳見 認證機制）
請求參數
| 參數 | 位置 | 類型 | 必填 | 說明 |
|---|---|---|---|---|
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": null,
"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 | 失敗時的錯誤訊息 |
其餘欄位與 POST /api/v1/imports 回應相同。
status 狀態流轉
pending → processing → completed
→ failed
stage 處理階段
| 階段 | 說明 |
|---|---|
converting | 音檔格式轉換中 |
transcribing | 語音辨識中 |
translating | 翻譯處理中 |
summarizing | 摘要生成中 |
completed 狀態的邊界情境（v1.3.5）
當音檔因靜音、音量過小、雜訊或辨識語言與音檔不符而辨識不出任何語音內容時，系統仍會以 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.5.7 最後更新：2026-05-20