WebSocket API

Voice Translation

概述

所有 voice-translation type 下可用的 action 一覽。關於連線與認證方式，請參考連線與認證；關於回應事件格式，請參考回應事件。

start - 開始語音翻譯
config - 設定術語庫/校正規則
audio - 傳送音訊
pause - 暫停翻譯
resume - 恢復翻譯
stop - 停止翻譯
retranslate - 重新翻譯單句
switch_language - 切換語言
set_name - 設定錄音名稱
rename_speaker - 全域重命名說話者
reassign_speaker - 修改單句語者身份
merge_speakers - 合併語者
tts_play - 播放 TTS
tts_stop - 停止 TTS
tts_mode - 切換 TTS 模式
set_tts - 互譯 TTS 設定
start_speaking - 開始說話（手動模式）
stop_speaking - 結束說話（手動模式）
switch_conversation_mode - 切換對話模式
set_speaker_language - 設定用戶語言
broadcast_go_live - 切換到正式階段
broadcast_announcement - 發送公告
set_standby_message - 設定預備階段文字

start - 開始語音翻譯

功能說明

開始一個新的語音翻譯工作階段，並根據設定的參數開始處理音訊。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `start`
`transcription_languages`	string	是	語音辨識語言（最多 2 個）
`translation_languages`	string	否	翻譯目標語言（空=不翻譯）
`realtime_translation`	boolean	否	即時翻譯模式（預設 `false`）
`recognition_mode`	string	否	辨識模式：`single`（單人，預設）、`multi_speaker`（多人）；`multi_speaker` 下 `transcription_languages` 必須恰好 1 個，否則回傳 `diarization_multilang_conflict` 錯誤並拒絕開始
`type`	string	是	錄音類型：`transcribe`、`conversation`、`record`、`broadcast`
`audio_format`	string	否	音訊格式：`pcm`（預設）、`webm`
`summary_template`	string	條件	摘要模板（`transcribe` 必填，`conversation`/`broadcast` 可選）
`options`	object	否	語音辨識選項
`tts_enabled`	boolean	否	是否啟用 TTS 語音合成（預設 `false`）
`tts_language`	string	否	TTS 輸出語言（需在 `translation_languages` 中）
`tts_voice`	string	否	TTS 語音名稱（如 `en-US-JennyNeural`）
`tts_mode`	string	否	TTS 播放模式：`sync`（同步，預設）、`async`（非同步）
`broadcast_token`	string	條件	廣播 Token（`broadcast` 類型必填，從 REST API 取得）
`active_language`	string	否	互譯模式初始 active 語言（預設 `transcription_languages[0]`）
`tts_config`	object	否	多語言 TTS 設定（廣播/互譯模式）
`broadcast_phase`	string	否	廣播初始階段：`standby`（預備）、`live`（正式，預設）
`standby_message`	string	否	預備階段觀眾看到的訊息（預設：「準備中，請稍候...」）
`name`	string	否	初始預設錄音名稱（最大 60 字，系統仍可覆蓋；未提供則自動生成如 `Transcription #1`）
`summary_language`	string	否	摘要輸出語言（不指定時預設使用辨識語言；廣播模式自動從頻道設定讀取）
`summary_mode`	string	否	摘要模式 enum：`builtin`（套 IPEVO 內建模板，預設）/ `custom`（客戶 prompt 完整取代三層）。缺值時自動推斷 `builtin`
`summary_prompt`	string	否	custom mode 必填、builtin mode 視為補充指示。≤2000 字元
`summary_prompt_slug`	string	否	custom mode 必填、builtin mode 禁帶。客戶自家識別碼（≤64 字元，Unicode、禁控制字元；pass-through 保存於後端記錄，供歷史查詢）
`summary_plain_text`	boolean	否	摘要要求純文字輸出（預設 `false`；開啟後後端做 Markdown 後處理）
`speakers`	object	條件	互譯模式用戶語言設定（`conversation` 類型必填，恰好 2 位，見下方說明）
`conversation_mode`	string	否	互譯對話模式：`auto`（自動偵測，預設）、`manual`（手動 PTT）

請求範例（基本）

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "transcription_languages": ["zh-TW"],
    "translation_languages": ["en-US"],
    "realtime_translation": false,
    "type": "transcribe",
    "audio_format": "pcm",
    "summary_template": "meeting",
    "options": {
      "speaking_speed": "normal",
      "segmentation_mode": "auto",
      "profanity_handling": "mask"
    }
  }
}

請求範例（初始預設名稱）

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "transcription_languages": ["zh-TW"],
    "translation_languages": ["en-US"],
    "type": "transcribe",
    "audio_format": "pcm",
    "summary_template": "meeting",
    "name": "產品規劃會議"
  }
}

錄音名稱規則

情境	名稱	name_source	系統會覆蓋？
`start` 帶 `name` 參數	初始預設名稱	`default`	是
`start` 未帶 `name`	自動生成（如 `Transcription #1`、`Broadcast #3`）	`default`	是
使用 `set_name` 設定	用戶明確設定的名稱	`user`	否
Session 結束後系統自動生成	根據逐字稿內容生成摘要名稱	`llm`	—

注意：start 的 name 為初始預設名稱，Session 結束時系統仍可能覆蓋。若需固定名稱，請使用 set_name。

預設名稱格式（固定英文）：

錄音類型	預設名稱格式
`transcribe`	`Transcription #N`
`conversation`	`Conversation #N`
`record`	`Recording #N`
`broadcast`	`Broadcast #N`

N 為該用戶同類型錄音的流水號。名稱優先順序：user > llm > default。用戶設定名稱後，Session 結束時系統不會覆蓋。

請求範例（含 TTS）

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "transcription_languages": ["zh-TW"],
    "translation_languages": ["en-US"],
    "realtime_translation": true,
    "type": "transcribe",
    "tts_enabled": true,
    "tts_language": "en-US",
    "tts_voice": "en-US-JennyNeural",
    "tts_mode": "sync"
  }
}

請求範例（互譯模式 - 自動偵測）

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "type": "conversation",
    "transcription_languages": ["zh-TW", "en-US"],
    "active_language": "zh-TW",
    "audio_format": "pcm",
    "realtime_translation": true,
    "speakers": [
      { "id": 1, "language": "zh-TW" },
      { "id": 2, "language": "en-US" }
    ],
    "tts_config": {
      "zh-TW": { "voice": "zh-TW-HsiaoChenNeural", "speaking_rate": 1.0 },
      "en-US": { "voice": "en-US-JennyNeural", "speaking_rate": 1.0 }
    }
  }
}

請求範例（互譯模式 - 手動模式）

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "type": "conversation",
    "transcription_languages": ["zh-TW", "en-US"],
    "conversation_mode": "manual",
    "audio_format": "pcm",
    "realtime_translation": true,
    "speakers": [
      { "id": 1, "language": "zh-TW" },
      { "id": 2, "language": "en-US" }
    ],
    "tts_config": {
      "zh-TW": { "voice": "zh-TW-HsiaoChenNeural", "speaking_rate": 1.0 },
      "en-US": { "voice": "en-US-JennyNeural", "speaking_rate": 1.0 }
    }
  }
}

互譯模式特殊規則：

項目	說明
`transcription_languages`	必須恰好 2 個，且不可相同
`translation_languages`	不需提供（自動推導為非 active 的語言）
`active_language`	可選，預設 `transcription_languages[0]`
`recognition_mode`	強制 `single`（忽略 `speaker_diarization`）
`tts_enabled`	預設 `true`；設為 `false` 僅回傳文字翻譯
`tts_config`	可選，為兩個語言各自設定 TTS 語音；留空自動使用預設語音
`summary_template`	可選，提供時停止後自動生成摘要
`speakers`	互譯模式必填，指定每位用戶的語言（恰好 2 位）
`conversation_mode`	可選，`auto`（自動偵測，預設）或 `manual`（手動 PTT）

speakers 欄位說明：

欄位	類型	必填	說明
`id`	int	是	用戶編號（1 或 2）
`language`	string	是	該用戶的語言代碼（須在 `transcription_languages` 中）

conversation_mode 說明：

模式	說明
`auto`（預設）	系統自動偵測說話語言，自動斷句
`manual`	用戶透過 `start_speaking` / `stop_speaking` 控制說話時段，期間音訊合併為單一句子

成功回應

啟動成功後回傳 session_started 事件，包含完整的 Session 初始資訊。

一般錄音（transcribe / conversation / record）：

{
  "type": "voice-translation",
  "data": {
    "action": "session_started",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "recording_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "recording_type": "transcribe",
    "recognition_mode": "single",
    "message": "語音辨識已開始"
  }
}

廣播模式（broadcast）：

{
  "type": "voice-translation",
  "data": {
    "action": "session_started",
    "session_id": "550e8400-e29b-41d4-a716-446655440000",
    "task_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "recording_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "recording_type": "broadcast",
    "recognition_mode": "multi_speaker",
    "phase": "standby",
    "viewer_count": 0,
    "queue_count": 0,
    "peak_viewers": 0,
    "total_viewers": 0,
    "message": "語音辨識已開始"
  }
}

回應欄位說明請參考 session_started 事件。

錄音類型說明

type	說明	使用場景
`transcribe`	語音轉文字	會議記錄、訪談紀錄
`conversation`	對話記錄	雙向溝通、客服對話
`record`	單純錄音	語音備忘、快速記錄
`broadcast`	廣播/直播	講座、演講、直播內容

廣播模式說明（type: "broadcast"）

廣播模式時，語言設定會自動從廣播頻道設定取得，無需在 WebSocket 訊息中傳送。

必填參數：

參數	類型	說明
`type`	string	必須為 `"broadcast"`
`broadcast_token`	string	廣播 Token（透過 REST API 建立廣播後取得）
`audio_format`	string	音訊格式（`pcm` 或 `webm`）

可選參數（覆蓋廣播頻道設定）：

參數	類型	說明
`tts_config`	object	多語言 TTS 設定（覆蓋建立時的設定）
`summary_template`	string	摘要模板 slug（覆蓋建立時的設定，不提供則使用廣播頻道預設值）

自動設定的參數（可省略）：

transcription_languages：自動從廣播設定讀取
translation_languages：自動從廣播設定讀取
realtime_translation：廣播模式預設啟用
summary_template：自動從廣播設定讀取（WebSocket 傳入值優先）
summary_language：自動從廣播設定讀取（WebSocket 傳入值優先）

廣播階段說明：

broadcast_phase	說明	行為
`live`（預設）	正式階段	STT/翻譯結果廣播給觀眾，寫入逐字稿
`standby`	預備階段	STT/翻譯結果只給主講者，觀眾看到 standby_message

預備階段用途：讓主講者在正式開始前進行 STT/翻譯熱機測試，確認設備正常後再切換到正式階段。

廣播模式請求範例：

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "type": "broadcast",
    "broadcast_token": "a3f9",
    "audio_format": "pcm"
  }
}

廣播模式請求範例（預備階段 + 覆蓋摘要模板）：

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "type": "broadcast",
    "broadcast_token": "a3f9",
    "audio_format": "pcm",
    "broadcast_phase": "standby",
    "standby_message": "演講即將開始，請稍候...",
    "summary_template": "lecture"
  }
}

摘要模板優先順序：WebSocket start 傳入值 > 廣播頻道建立時設定的預設值。若兩者皆未設定，則不自動生成摘要。

廣播模式 TTS 設定（tts_config）：

透過 tts_config 參數指定哪些翻譯語言需要產生 TTS 語音給觀眾。

tts_config 欄位	類型	說明
voice	string	TTS 語音名稱
speaking_rate	number	語速（0.5~2.0，預設 1.0）

{
  "type": "voice-translation",
  "data": {
    "action": "start",
    "type": "broadcast",
    "broadcast_token": "a3f9",
    "audio_format": "pcm",
    "tts_config": {
      "en-US": {
        "voice": "en-US-JennyNeural",
        "speaking_rate": 1.0
      },
      "ja-JP": {
        "voice": "ja-JP-NanamiNeural",
        "speaking_rate": 1.0
      }
    }
  }
}

注意：
TTS 語言必須是 translation_languages 中的有效語言，無效語言會被自動忽略
主講者（WebSocket）不會收到 TTS 音訊，只有 SSE 觀眾會收到 tts_ready 事件
TTS 只在 live 階段發送，standby 階段不會發送

TTS 播放模式說明

模式	說明	行為
`sync`	同步模式（預設）	自動播放最新的 `is_final=true` 翻譯句子，若前一句仍在播放則進入佇列等待
`async`	非同步模式（手動控制）	用戶可選擇任何已翻譯的句子進行 TTS，使用 `tts_play` 指令控制

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`missing_transcription_languages`	400	未提供語言參數	確認請求包含 `transcription_languages`
`invalid_transcription_language`	400	無效的語言代碼	確認語言代碼格式正確（如 `zh-TW`）
`too_many_languages`	400	語言數量超過上限	最多只能指定 2 個語言
`invalid_recording_type`	400	錄音類型無效	使用有效的類型值
`invalid_summary_template`	400	摘要模板無效	確認模板識別碼正確
`stt_init_failed`	503	服務初始化失敗	稍後重試
`auth_budget_exceeded`	402	月度預算已超額	等待下月預算重置或調整預算
`tts_init_failed`	503	TTS 服務初始化失敗	稍後重試
`tts_invalid_language`	400	TTS 語言不在翻譯語言中	確認 `tts_language` 在 `translation_languages` 中
`broadcast_token_required`	400	廣播模式需要 Token	`broadcast` 類型必須提供 `broadcast_token`
`broadcast_token_invalid`	400	廣播 Token 無效	確認 Token 正確且未過期
`broadcast_not_ready`	503	廣播服務尚未啟動	稍後重試
`summary_invalid_mode`	400	`summary_mode` 不是 `builtin` / `custom`	改為合法 mode
`summary_mode_field_mismatch`	400	mode 與欄位組合不符（必填缺漏 / 禁帶被帶入）	依 mode 規則調整欄位
`summary_prompt_too_long`	400	`summary_prompt` 超過 2000 字元	縮短自訂 prompt
`summary_prompt_slug_too_long`	400	`summary_prompt_slug` 超過 64 字元	縮短識別碼
`summary_prompt_slug_invalid`	400	`summary_prompt_slug` 含控制字元（`\n` / `\r` / `\t` / `\0` 等）	移除控制字元

config - 設定術語庫/校正規則

功能說明

在錄音開始前或進行中傳入術語庫、模糊詞校正規則和翻譯字典設定。這些設定可提升 STT 識別率、修正同音字錯誤、確保翻譯一致性。

自動生成校正規則：當傳入 terminology 時，系統會自動為每個術語生成模糊詞校正規則（同音字、近音字、繁簡體變體）。前端無需手動定義 fuzzy_correction，大幅簡化設定流程。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `config`
`terminology`	object	否	術語庫設定
`fuzzy_correction`	object	否	模糊詞校正規則
`translation_dict`	object	否	翻譯字典

注意：至少需要提供一個設定項目。

術語庫格式（terminology）

以語言代碼為 key，術語陣列為 value：

{
  "zh-TW": [
    { "term": "語者分離", "boost": 1.5 },
    { "term": "WebSocket", "boost": 2.0 }
  ],
  "en-US": [
    { "term": "diarization", "boost": 1.5 }
  ]
}

欄位	類型	必填	說明
`term`	string	是	術語（最大 100 字元）
`boost`	number	否	權重（預設 1.0，範圍 0.5-5.0）

限制：每種語言最多 500 個術語。

模糊詞校正格式（fuzzy_correction）

注意：此欄位通常不需要手動設定。系統會根據 terminology 自動生成校正規則。僅在需要自訂特殊規則時使用。

以語言代碼為 key，校正規則陣列為 value：

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

欄位	類型	必填	說明
`correct`	string	是	正確詞彙
`incorrect`	string	是	錯誤變體列表

翻譯字典格式（translation_dict）

直接使用條目陣列：

[
  {
    "source": "語者分離",
    "translations": {
      "en-US": "Speaker Diarization",
      "ja-JP": "話者分離"
    }
  }
]

欄位	類型	必填	說明
`source`	string	是	來源詞彙（使用 STT 語言）
`translations`	object	是	翻譯對照 `{ "語言代碼": "翻譯" }`

限制：建議不超過 50 條目（避免處理效能下降）。

請求範例（推薦：只設定術語庫）

{
  "type": "voice-translation",
  "data": {
    "action": "config",
    "terminology": {
      "zh-TW": [
        { "term": "語者分離", "boost": 1.5 },
        { "term": "CVD製程", "boost": 1.5 },
        { "term": "wafer良率", "boost": 1.5 }
      ]
    }
  }
}

請求範例（完整設定，含手動校正規則）

{
  "type": "voice-translation",
  "data": {
    "action": "config",
    "terminology": {
      "zh-TW": [
        { "term": "語者分離", "boost": 1.5 },
        { "term": "即時轉錄", "boost": 1.5 }
      ]
    },
    "fuzzy_correction": {
      "zh-TW": [
        { "correct": "語者分離", "incorrect": ["語這分離", "語者分力"] }
      ]
    },
    "translation_dict": [
      { "source": "語者分離", "translations": { "en-US": "Speaker Diarization" } }
    ]
  }
}

成功回應

{
  "type": "voice-translation",
  "data": {
    "action": "config_updated",
    "updated": ["terminology", "fuzzy_correction", "translation_dict"],
    "message": "設定已更新"
  }
}

回應欄位說明請參考 config_updated 事件。

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`config_empty`	400	未提供任何設定	至少提供一個設定項目
`config_term_too_long`	400	術語超過 100 字元	縮短術語長度
`config_too_many_entries`	400	術語數量超過 500 個	減少術語數量
`config_too_many_dict_entries`	400	翻譯字典超過 50 條目	減少字典條目

audio - 傳送音訊

功能說明

傳送音訊資料給伺服器進行語音辨識。音訊需經過 Base64 編碼後傳送。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `audio`
`payload`	string	是	Base64 編碼的音訊資料

音訊格式要求

PCM 格式（預設）：

項目	規格
格式	PCM（原始音訊）
取樣率	16000 Hz
位元深度	16-bit
聲道	Mono（單聲道）
位元組順序	Little-endian
傳輸編碼	Base64

WebM/Opus 格式：

項目	規格
格式	WebM 容器 + Opus 編碼
取樣率	任意（伺服器自動轉換）
聲道	Mono 或 Stereo（伺服器自動轉換）
傳輸編碼	Base64

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "audio",
    "payload": "Base64 編碼的 PCM 音訊資料"
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`session_not_started`	400	語音辨識尚未開始	先呼叫 `start` action
`audio_invalid_format`	400	音訊資料格式錯誤	確認 Base64 編碼正確
`audio_format_unsupported`	400	不支援的音訊格式	使用 `pcm` 或 `webm` 格式
`audio_decode_failed`	400	音訊解碼失敗	確認音訊格式正確
`audio_process_failed`	500	STT/語者辨識寫入持續失敗，超過容忍閾值	建議重新連線

pause - 暫停翻譯

功能說明

暫停語音辨識處理。暫停期間收到的音訊會被快取，恢復後繼續處理。

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "pause"
  }
}

成功回應

{
  "type": "voice-translation",
  "data": {
    "action": "status",
    "message": "語音辨識已暫停"
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`session_not_started`	400	語音辨識尚未開始	先呼叫 `start`
`session_already_paused`	400	已經暫停	可忽略此錯誤

resume - 恢復翻譯

功能說明

恢復已暫停的語音辨識處理。

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "resume"
  }
}

成功回應

{
  "type": "voice-translation",
  "data": {
    "action": "status",
    "message": "語音辨識已恢復"
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`session_not_started`	400	語音辨識尚未開始	先呼叫 `start`
`session_not_paused`	400	未暫停	可忽略此錯誤

stop - 停止翻譯

功能說明

停止語音辨識並結束會話。系統會自動上傳音檔和逐字稿，並生成摘要（若有設定）。

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "stop"
  }
}

成功回應

{
  "type": "voice-translation",
  "data": {
    "action": "status",
    "message": "語音辨識已停止"
  }
}

停止後，當音檔和逐字稿上傳完成，會收到 task_complete 事件，包含 task_id（Recording UUID）。

retranslate - 重新翻譯單句

功能說明

對指定句子重新翻譯，適用於修正原文後需要更新翻譯的情況。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `retranslate`
`sid`	int	是	要重翻的句子編號
`translation_languages`	string	是	翻譯語言代碼陣列
`text`	string	是	要翻譯的原文（用戶修正後的文字）

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "retranslate",
    "sid": 1,
    "translation_languages": ["en-US"],
    "text": "用戶修正後的原文"
  }
}

成功回應

回傳 translation 事件（與正常翻譯結果共用 schema），翻譯結果中會包含 is_retranslation: true：

{
  "type": "voice-translation",
  "data": {
    "action": "translation",
    "translations": {
      "en-US": {
        "sid": 1,
        "text": "新的翻譯結果",
        "is_final": true,
        "is_retranslation": true
      }
    }
  }
}

v1.5.6 文件修正：早期文件描述 retranslate 回 action: "result"，實際 wire 上是 action: "translation"。若客戶端原本 dispatcher 對 result action 處理，請新增 translation action 的處理分支。

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`retranslate_sid_not_found`	400	找不到指定的 SID	確認 SID 存在
`retranslate_session_not_active`	400	工作階段未啟動或已結束	確認工作階段狀態
`retranslate_no_target_lang`	400	未提供目標語言	提供 `translation_languages`
`retranslate_no_text`	400	未提供要翻譯的文字	提供 `text` 參數
`retranslate_llm_failed`	500	翻譯服務失敗	稍後重試

switch_language - 切換語言

功能說明

在即時翻譯進行中切換語言。行為依錄音類型而異：

一般模式（transcribe 等）：切換翻譯目標語言，並自動批次重翻所有已翻譯句子
互譯模式（conversation）：切換 STT 來源語言（說話語言），翻譯目標自動切換為另一語言

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `switch_language`
`translation_languages`	string	條件	翻譯語言代碼陣列（一般模式必填）
`transcription_languages`	string	條件	切換目標語言（互譯模式；不帶則自動 toggle 到另一語言）

請求範例（一般模式）

{
  "type": "voice-translation",
  "data": {
    "action": "switch_language",
    "translation_languages": ["ja-JP"]
  }
}

請求範例（互譯模式）

指定切換目標：

{
  "type": "voice-translation",
  "data": {
    "action": "switch_language",
    "transcription_languages": ["en-US"]
  }
}

自動 toggle（不帶參數）：

{
  "type": "voice-translation",
  "data": {
    "action": "switch_language"
  }
}

互譯模式特殊行為：

互譯模式使用自動語言偵測，通常不需要手動切換語言
switch_language 僅更新內部偏好狀態
切換成功後回傳 language_switched 事件（非 language_switch_start/done 序列）
切換到相同語言會回傳 conversation_same_language 警告

回應序列（一般模式）

切換語言後會依序收到以下事件：

language_switch_start：通知開始切換

{
  "type": "voice-translation",
  "data": {
    "action": "language_switch_start",
    "translation_language": "ja-JP",
    "total_segments": 15,
    "message": "開始切換語言並重新翻譯"
  }
}

batch_retranslation（多個）：逐句回傳重翻結果

{
  "type": "voice-translation",
  "data": {
    "action": "batch_retranslation",
    "sid": 3,
    "translations": {
      "ja-JP": {
        "sid": 3,
        "text": "今日はプロジェクトの進捗について話し合いましょう",
        "is_final": true,
        "is_retranslation": true
      }
    }
  }
}

language_switch_done：通知切換完成

{
  "type": "voice-translation",
  "data": {
    "action": "language_switch_done",
    "translation_language": "ja-JP",
    "success_count": 15,
    "failed_count": 0,
    "message": "語言切換完成"
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`switch_language_no_target`	400	未提供目標語言	提供 `translation_languages`
`switch_language_in_progress`	400	前一次切換尚未完成	等待切換完成
`switch_language_same_target`	400	目標語言與當前相同	可忽略此錯誤
`conversation_requires_two_languages`	400	互譯模式需恰好兩個語言	確認 transcription_languages 為 2 個
`conversation_languages_identical`	400	互譯的兩個語言不可相同	提供兩個不同的語言
`conversation_invalid_language`	400	無效的互譯語言	確認語言在 transcription_languages 中
`conversation_same_language`	400	已是當前語言	可忽略此警告

set_name - 設定錄音名稱

功能說明

在錄音進行中設定名稱。設定後 name_source 翻轉為 user，錄音結束時系統不會覆蓋（即使 LLM 生成了摘要名稱也會被讓位）。name_source 完整語意與優先順序見上方 § 錄音名稱規則。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `set_name`
`name`	string	是	錄音名稱（最大 60 字）

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "set_name",
    "name": "產品規劃會議"
  }
}

成功回應

{
  "type": "voice-translation",
  "data": {
    "action": "status",
    "message": "錄音名稱已設定"
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`set_name_empty`	400	錄音名稱為空	提供非空名稱
`set_name_too_long`	400	錄音名稱超過限制	縮短名稱長度（≤60 字）
`set_name_not_ready`	400	錄音尚未就緒	等 `session_started` 後再呼叫
`session_not_started`	400	語音辨識尚未開始	先呼叫 `start`

rename_speaker - 全域重命名說話者

功能說明

在多人語者分離模式（multi_speaker）下，全域重命名某個說話者。所有使用該說話者 ID 的句子都會同步更新。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `rename_speaker`
`speaker_id`	string	是	原始語者 ID（如 `Guest-1`），可同時接受目前的顯示標籤做連續改名；最大 100 字元
`new_label`	string	是	新顯示標籤；最大 100 字元，不得含控制字元（`\x00-\x1F`、`\x7F`）或換行

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "rename_speaker",
    "speaker_id": "Guest-1",
    "new_label": "王經理"
  }
}

成功回應

回傳 speaker_renamed 事件：

{
  "type": "voice-translation",
  "data": {
    "action": "speaker_renamed",
    "speaker_id": "Guest-1",
    "new_label": "王經理",
    "affected_sids": [1, 3, 5, 8]
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`speaker_not_found`	400	找不到指定的說話者	確認說話者 ID 或別名存在
`speaker_name_empty`	400	說話者名稱不能為空	提供有效的名稱
`speaker_name_duplicate`	422	說話者名稱已被使用	使用其他名稱，或先修改衝突的說話者
`session_not_started`	400	語音辨識尚未開始	先呼叫 `start`

reassign_speaker - 修改單句語者身份

功能說明

修改特定句子的語者身份（OriginalSpeakerID），將句子指派給既有語者。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `reassign_speaker`
`sid`	int	是	要修改的句子編號
`target_speaker_id`	string	是	目標語者原始 ID（取自 `init_sentence.speaker_id`；reassign 不接受顯示標籤）

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "reassign_speaker",
    "sid": 5,
    "target_speaker_id": "Guest-2"
  }
}

成功回應

回傳 speaker_reassigned 事件：

{
  "type": "voice-translation",
  "data": {
    "action": "speaker_reassigned",
    "sid": 5,
    "old_speaker_id": "Guest-1",
    "new_speaker_id": "Guest-2",
    "new_speaker_label": "李小華"
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`speaker_sid_not_found`	400	找不到指定的句子	確認 SID 存在
`speaker_not_found`	400	目標語者不存在	使用已存在的語者 ID
`speaker_name_empty`	400	目標語者 ID 不能為空	提供有效的語者 ID
`session_not_started`	400	語音辨識尚未開始	先呼叫 `start`
`invalid_parameter`	400	不支援建立新語者	使用已存在的語者 ID

merge_speakers - 合併語者

功能說明

將一個語者的所有句子合併到另一個語者。合併後，該語者未來產生的辨識結果也會自動轉換為目標語者。

與 `reassign_speaker` 的差異

功能	作用範圍	未來影響
`reassign_speaker`	單句（1 個 SID）	無
`merge_speakers`	該語者的所有句子	未來出現的 source 也自動轉為 target

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `merge_speakers`
`source_speaker_id`	string	是	要被合併的語者 ID（如 `Guest-2`）
`target_speaker_id`	string	是	合併目標語者 ID（如 `Guest-1`）

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "merge_speakers",
    "source_speaker_id": "Guest-2",
    "target_speaker_id": "Guest-1"
  }
}

成功回應

回傳 speakers_merged 事件：

{
  "type": "voice-translation",
  "data": {
    "action": "speakers_merged",
    "source_speaker_id": "Guest-2",
    "target_speaker_id": "Guest-1",
    "target_speaker_label": "王經理",
    "affected_sids": [3, 5, 7]
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`speaker_not_found`	400	語者不存在	確認語者 ID 存在
`merge_speakers_same_id`	400	來源和目標語者相同	使用不同的語者 ID
`speaker_name_empty`	400	語者 ID 不能為空	提供有效的語者 ID
`session_not_started`	400	語音辨識尚未開始	先呼叫 `start`

tts_play - 播放 TTS

功能說明

在 async 模式下，手動播放指定句子的 TTS 語音。支援對同一個 sid 重複請求（重播）。

互譯模式（conversation）：tts_play 會自動根據 tts_config 中的語音設定合成對應語言的翻譯，不需額外指定 tts_language。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `tts_play`
`sid`	int	是	起始句子 ID
`length`	int	否	播放句子數量（預設 1，最大 20）

請求範例（單句播放）

{
  "type": "voice-translation",
  "data": {
    "action": "tts_play",
    "sid": 5
  }
}

請求範例（多句播放）

{
  "type": "voice-translation",
  "data": {
    "action": "tts_play",
    "sid": 5,
    "length": 3
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`tts_not_enabled`	400	TTS 未啟用	確認 start 時啟用 TTS
`tts_segment_not_found`	400	找不到指定的句子	確認 SID 存在
`tts_translation_not_found`	400	該句子沒有指定語言的翻譯	確認翻譯存在

tts_stop - 停止 TTS

功能說明

停止當前正在播放的 TTS 語音。

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "tts_stop"
  }
}

成功回應

{
  "type": "voice-translation",
  "data": {
    "action": "status",
    "message": "TTS 播放已停止"
  }
}

tts_mode - 切換 TTS 模式

功能說明

在錄音進行中切換 TTS 播放模式（同步/非同步）。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `tts_mode`
`tts_mode`	string	是	模式：`sync`（同步）或 `async`（非同步）

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "tts_mode",
    "tts_mode": "async"
  }
}

成功回應

回傳 tts_mode_changed 事件：

{
  "type": "voice-translation",
  "data": {
    "action": "tts_mode_changed",
    "tts_mode": "async"
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`tts_not_enabled`	400	TTS 未啟用	確認 start 時啟用 TTS
`invalid_data`	422	無效的模式	使用 `sync` 或 `async`

set_tts - 互譯 TTS 設定

功能說明

在互譯模式（conversation）進行中，途中切換 TTS 開關或更新 TTS 語音設定。僅在 conversation 類型下可用。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `set_tts`
`tts_enabled`	boolean	否	設定 TTS 開關
`tts_config`	object	否	更新特定語言的 TTS 設定（僅互譯的兩個語言有效）

請求範例（關閉 TTS）

{
  "type": "voice-translation",
  "data": {
    "action": "set_tts",
    "tts_enabled": false
  }
}

請求範例（更新 TTS 語音）

{
  "type": "voice-translation",
  "data": {
    "action": "set_tts",
    "tts_enabled": true,
    "tts_config": {
      "en-US": { "voice": "en-US-GuyNeural", "speaking_rate": 1.2 }
    }
  }
}

成功回應

回傳 tts_updated 事件：

{
  "type": "voice-translation",
  "data": {
    "action": "tts_updated",
    "tts_enabled": true,
    "tts_config": {
      "zh-TW": { "voice": "zh-TW-HsiaoChenNeural", "speaking_rate": 1.0 },
      "en-US": { "voice": "en-US-GuyNeural", "speaking_rate": 1.2 }
    }
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`invalid_action`	400	非互譯模式不支援此操作	僅在 conversation 類型下使用

start_speaking - 開始說話（手動模式）

功能說明

在互譯手動模式（conversation_mode: "manual"）下，通知系統用戶開始說話。從此刻起，音訊會被傳送至 STT 進行辨識，所有辨識結果會累積為同一句話（不自動斷句）。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `start_speaking`
`speaker`	int	是	用戶編號（1 或 2）

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "start_speaking",
    "speaker": 1
  }
}

成功回應

{
  "type": "voice-translation",
  "data": {
    "action": "status",
    "message": "開始說話"
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`invalid_action`	400	非互譯模式	僅在 conversation 類型下使用
`conversation_not_manual_mode`	400	非手動模式	僅在 manual 模式下使用
`conversation_speaking`	400	已在說話中	先呼叫 `stop_speaking`
`conversation_invalid_speaker`	400	無效的用戶編號	使用 1 或 2

stop_speaking - 結束說話（手動模式）

功能說明

在互譯手動模式下，通知系統用戶結束說話。系統會將期間累積的辨識結果合併為一個完整句子，進行翻譯和 TTS 合成。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `stop_speaking`

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "stop_speaking"
  }
}

成功回應

結束說話後，系統會送出完整的 result 事件（包含 origin 和 translations）：

{
  "type": "voice-translation",
  "data": {
    "action": "result",
    "origin": {
      "sid": 1,
      "language": "zh-TW",
      "text": "這段期間所有辨識內容合併的完整句子",
      "is_final": true,
      "speaker_id": "Speaker-1",
      "start_time": "00:05"
    },
    "translations": {
      "en-US": {
        "sid": 1,
        "text": "The complete merged sentence from this speaking period",
        "is_final": true
      }
    }
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`invalid_action`	400	非互譯模式	僅在 conversation 類型下使用
`conversation_not_speaking`	400	未在說話狀態	先呼叫 `start_speaking`

switch_conversation_mode - 切換對話模式

功能說明

在互譯模式進行中，切換自動偵測模式（auto）與手動模式（manual）。切換時若正在說話中會自動結束說話。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `switch_conversation_mode`
`conversation_mode`	string	是	目標模式：`auto` 或 `manual`

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "switch_conversation_mode",
    "conversation_mode": "manual"
  }
}

成功回應

回傳 conversation_mode_changed 事件：

{
  "type": "voice-translation",
  "data": {
    "action": "conversation_mode_changed",
    "conversation_mode": "manual"
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`invalid_action`	400	非互譯模式	僅在 conversation 類型下使用
`conversation_invalid_mode`	400	無效的對話模式	使用 `auto` 或 `manual`

set_speaker_language - 設定用戶語言

功能說明

在互譯模式進行中，即時變更指定用戶的語言。系統會重建 STT 連線以適應新語言，翻譯目標也會自動更新。變更前的逐字稿內容維持原語言不變，時間戳持續計算不歸零。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `set_speaker_language`
`speaker`	int	是	用戶編號（1 或 2）
`language`	string	是	新的語言代碼（如 `ja-JP`）

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "set_speaker_language",
    "speaker": 1,
    "language": "ja-JP"
  }
}

成功回應

回傳 speaker_language_changed 事件：

{
  "type": "voice-translation",
  "data": {
    "action": "speaker_language_changed",
    "speaker_language_map": {
      "1": "ja-JP",
      "2": "en-US"
    }
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`invalid_action`	400	非互譯模式	僅在 conversation 類型下使用
`conversation_invalid_speaker`	400	無效的用戶編號	使用 1 或 2
`conversation_invalid_language`	400	無效的語言代碼	使用有效的 BCP 47 語言代碼
`conversation_same_language`	400	與當前語言相同	可忽略此警告
`conversation_language_same_as_peer`	400	新語言與另一位用戶相同	兩位用戶語言不可相同
`conversation_speaking`	400	正在說話中，無法變更語言	先結束說話再變更
`conversation_language_change_failed`	500	語言變更失敗（STT 重建失敗）	稍後重試

broadcast_go_live - 切換到正式階段

功能說明

在廣播預備階段（standby）切換到正式階段（live）。切換後，STT/翻譯結果開始廣播給觀眾，並開始寫入逐字稿。

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "broadcast_go_live"
  }
}

成功回應

回傳 broadcast_phase_changed 事件：

{
  "type": "voice-translation",
  "data": {
    "action": "broadcast_phase_changed",
    "phase": "live",
    "message": "廣播已開始"
  }
}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`broadcast_not_enabled`	400	非廣播模式	確認 `type: "broadcast"`

注意：若已在正式階段（live），會回傳狀態訊息「廣播已經在進行中」，不視為錯誤。

broadcast_announcement - 發送公告

功能說明

主講者發送自訂訊息公告給所有觀眾。觀眾會透過 SSE 收到 announcement 事件。公告訊息會自動翻譯成所有翻譯語言，觀眾收到的 SSE 事件會包含 translations 欄位。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `broadcast_announcement`
`message`	string	是	公告訊息內容

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "broadcast_announcement",
    "message": "會議將在 5 分鐘後結束"
  }
}

成功回應

{
  "type": "voice-translation",
  "data": {
    "action": "status",
    "message": "公告已發送"
  }
}

觀眾端收到的 SSE 事件（含翻譯）：

event: announcement
data: {"message":"會議將在 5 分鐘後結束","translations":{"en-US":"The meeting will end in 5 minutes","ja-JP":"会議は5分後に終了します"}}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`broadcast_not_enabled`	400	非廣播模式	確認 `type: "broadcast"`
`invalid_parameter`	400	訊息為空	提供有效的 `message` 參數

set_standby_message - 設定預備階段文字

功能說明

在廣播預備階段（standby）動態設定顯示給觀眾的訊息。允許主講者進入預備模式後再設定等待訊息，而非在 start 時就必須提供。

訊息會自動翻譯成所有翻譯語言，觀眾收到的 SSE 事件會包含 translations 欄位。

請求參數

參數	類型	必填	說明
`action`	string	是	固定為 `set_standby_message`
`message`	string	是	預備階段顯示文字（將透過翻譯流程翻譯給各語言觀眾）

請求範例

{
  "type": "voice-translation",
  "data": {
    "action": "set_standby_message",
    "message": "演講即將開始，請稍候..."
  }
}

成功回應

{
  "type": "voice-translation",
  "data": {
    "action": "status",
    "message": "預備階段文字已更新"
  }
}

觀眾端收到的 SSE 事件（含翻譯）：

event: standby
data: {"message":"演講即將開始，請稍候...","translations":{"en-US":"The presentation is about to begin, please wait...","ja-JP":"プレゼンテーションがまもなく始まります。お待ちください..."}}

錯誤碼

錯誤碼	HTTP 狀態碼	說明	處理建議
`broadcast_not_enabled`	400	非廣播模式	確認 `type: "broadcast"`
`broadcast_not_in_standby`	400	不在預備階段	只能在 standby 階段使用

注意：此 action 只能在預備階段（standby）使用。若已進入正式階段（live），會回傳錯誤。

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

Events

Curl