開始使用

Concepts

Task（任務）

Task 是 VAS 中最頂層的概念，代表一次完整的語音處理工作。每個 Task 有一個唯一的 task_id（UUID），完成後可透過 REST API 查詢和管理。

Task 可透過以下方式產生：

即時錄音：透過 WebSocket 進行語音翻譯後自動建立
音檔匯入：上傳音檔處理完成後自動建立

Recording（錄音）

Recording 是 Task 的核心資料，包含音訊檔案和逐字稿。每個 Task 對應一個 Recording。

錄音類型

類型	說明	使用場景
`transcribe`	語音轉文字	會議記錄、訪談紀錄
`conversation`	雙語即時互譯	兩人跨語言對話、即時口譯
`record`	單純錄音	語音備忘、快速記錄
`broadcast`	廣播/直播	講座、演講、直播內容

類型差異

功能	transcribe	conversation	record	broadcast
語音辨識	v	v	v	v
翻譯	v	v（雙向互譯）	-	v
TTS 語音回傳	v（手動觸發）	v（自動）	-	v（廣播觀眾）
摘要	v（必填模板）	v（可選）	-	v（可選）
廣播	-	-	-	v

處理狀態（Processing Status）

Recording 從建立到完成會經歷多個處理狀態，可透過 GET /api/v1/tasks?status=active 查詢進行中的任務。

狀態	說明	觸發場景
`recording`	即時錄音進行中	WebSocket 開始錄音、廣播開始
`importing`	音檔匯入處理中	音檔上傳後
`uploading`	上傳至雲端儲存中	錄音停止後、匯入完成後
`processing`	語音辨識與翻譯處理中	上傳完成後
`completed`	處理完成	最終狀態
`failed`	處理失敗	最終狀態

即時錄音/廣播：recording → uploading → processing → completed / failed
音檔匯入：    importing → uploading → processing → completed / failed

Session（會話）

Session 是一次 WebSocket 連線中的活動工作階段，從 start 到 stop。

Session 生命週期

連線 WebSocket
    │
    ▼
  start  ──→  session_started（取得 session_id + recording_id）
    │
    ▼
  傳送音訊（audio）──→ 接收辨識結果（result）
    │
    ├── pause / resume（可選）
    ├── config（可選，更新術語庫）
    ├── retranslate（可選，重新翻譯）
    ├── switch_language（可選，切換語言）
    ├── set_tts（互譯模式，切換 TTS 開關/設定）
    │
    ▼
  stop   ──→  status（停止確認）
    │
    ▼
  task_complete（音檔和逐字稿上傳完成，取得 task_id）

說話者辨識模式

模式	說明	適用場景
`single`	單人模式（預設）	單人演講、備忘錄
`multi_speaker`	多人對話模式	會議、訪談、對話（支援 31 種語言）

多人模式下，系統會自動辨識不同的說話者並標記為 Guest-1、Guest-2 等。你可以透過以下操作管理說話者：

重命名：將 Guest-1 重命名為實際姓名
重新指派：修改某句話的說話者歸屬
合併：將兩個說話者合併為一個

詳細說明請參考說話者管理指南。

資料流

麥克風音訊
    │
    ▼
  語音辨識（STT）──→ 原文（origin）
    │
    ▼
  翻譯    ──→ 翻譯結果（translation）
    │
    ├── 即時翻譯：每句辨識完成立即翻譯
    └── 非即時翻譯：等待 is_final 後才翻譯
    │
    ▼
  TTS 語音合成（可選）──→ 音訊（tts_ready）
    │
    ▼
  會議摘要（可選）──→ 摘要結果

即時翻譯 vs 非即時翻譯

模式	`realtime_translation`	行為
非即時（預設）	`false`	等待句子確認（`is_final: true`）後翻譯，結果更準確
即時	`true`	每次辨識更新都觸發翻譯，延遲更低但可能多次更新

互譯模式

互譯模式讓兩個說不同語言的人透過單一 WebSocket 連線進行即時互譯對話。系統自動偵測每句話的語言，翻譯方向自動對應，整個過程對使用者完全透明。

Person A 說中文 → 自動偵測 zh-TW → 翻譯成 en-US → TTS(en-US 語音) → tts_ready
Person B 說英文 → 自動偵測 en-US → 翻譯成 zh-TW → TTS(zh-TW 語音) → tts_ready

互譯模式特性

項目	說明
連線模式	單一 WebSocket 連線，兩人共用一台裝置
語言數量	恰好 2 個（如 zh-TW + en-US）
辨識模式	自動偵測語言
語言偵測	逐句自動偵測，不需手動切換
TTS 回傳	翻譯結果自動 TTS 合成（可關閉，途中可透過 `set_tts` 切換）
摘要	支援可選自動摘要（`summary_template`）

互譯流程概覽

WebSocket：以 conversation 類型開始，指定兩個語言
傳送音訊：系統自動偵測語言，翻譯為另一語言並回傳 TTS
語言自動偵測：每句話獨立偵測，origin.language 反映偵測到的語言
停止：停止錄音，處理完成後自動建立 Task

詳細說明請參考即時語音翻譯指南的互譯模式章節。

廣播架構

廣播功能讓一位主講者的語音即時傳達給多位觀眾。

主講者（WebSocket）
    │
    ├── 傳送音訊 ──→ STT ──→ 翻譯 ──→ TTS（可選）
    │
    ▼
  VAS 伺服器
    │
    ▼
觀眾 1（SSE）──→ 即時字幕 + TTS 音訊
觀眾 2（SSE）──→ 即時字幕 + TTS 音訊
觀眾 N（SSE）──→ 即時字幕 + TTS 音訊

廣播階段

階段	說明
`standby`（預備）	主講者可以測試設備，觀眾看到等待訊息
`live`（正式）	即時字幕廣播給所有觀眾

廣播流程概覽

REST API：建立廣播頻道，取得 broadcast_token
WebSocket：主講者以 broadcast 類型開始錄音
SSE：觀眾透過分享連結連線接收字幕
WebSocket：主講者停止錄音，廣播結束

詳細說明請參考廣播功能指南。

摘要模板

摘要模板定義了自動摘要的生成格式。在 transcribe 類型的錄音中，summary_template 為必填參數；在 conversation 和 broadcast 類型中為可選參數。

可透過 Summary Templates API 查詢可用的模板列表。

術語庫與文字處理

VAS 提供三種文字處理設定，可在錄音前或錄音中動態設定：

設定	說明
術語庫（terminology）	提升特定詞彙的辨識準確度
模糊詞校正（fuzzy_correction）	自動修正同音字、近音字錯誤（系統可自動生成）
翻譯字典（translation_dict）	確保專有名詞的翻譯一致性

詳細說明請參考 WebSocket voice-translation 參考的 config action。

Webhook 回呼

VAS 支援 Webhook 通知，在錄音處理完成或失敗時主動推送事件到您指定的 URL，免除輪詢的需要。

支援的事件

事件	說明
`recording.completed`	錄音處理完成
`recording.failed`	錄音處理失敗
`import.completed`	音檔匯入完成
`import.failed`	音檔匯入失敗

設定方式

請求級：在 API 請求中加入 callback_url 參數（音檔匯入、廣播）
API Key 級：在 API Key 設定中指定 webhook_url（適用所有請求）

詳細說明請參考 Webhook 回呼指南。

版本：V1.5.7 最後更新：2026-05-20

Authentication

Quickstart