歷史版本紀錄

V1.18 以前的版本紀錄，最新內容見 版本更新紀錄。

V1.18.6

2026-09-29

修正：廣播字幕的完整句子

• 觀眾中途進場時，補送的歷史字幕都是完整句子。
• 已在線的觀眾，已經完成的字幕不會退回未完成。

V1.18.5

2026-09-29

修正：部分轉錄語言的音檔匯入時長與扣點

適用於第一個轉錄語言為下列語言的音檔匯入：wuu-CN、yue-CN、zh-CN-shandong、zh-CN-sichuan、ar-DZ、ar-MA、ar-TN、ar-YE、as-IN、gu-IN、kn-IN、mr-IN、or-IN、pa-IN、fr-BE、fr-CA、fr-CH、it-CH、nl-BE、bs-BA、km-KH、ne-NP、si-LK、sw-TZ。

• 時長與扣點依音檔實際長度計算；本版以前可能與實際長度不符，逐字稿也可能不正確。
• 1～5 秒的短音檔可正常完成。
• 無法讀取的音檔以 failed 結束（error_code 為 import_stt_failed），不扣點。

V1.18.4

2026-09-29

修正：沒有收到音訊的錄音不計費

• 整場沒有收到可用音訊的錄音不計費，已扣的點數會自動退回。

V1.18.3

2026-09-28

修正：音訊無法辨識時的處理

• 錄音中遇到無法辨識的音訊時，錄音會繼續，並回傳 audio_decode_failed；重新送出新的音訊串流即可恢復。
• 斷線續接後，請一律送出新的音訊串流。
• 無法辨識的期間不計費。

V1.18.2

2026-09-28

文件更新

• 廣播指南與 API 參考更正 share_url 的說明：share_url 不是可開啟的觀眾頁面，請勿直接分享給觀眾。觀眾頁面由您的應用程式提供，以 token 依觀眾端流程接入。API 行為未變。

V1.18.1

2026-09-27

修正：profanity_handling 設定生效

WebSocket start 的 options.profanity_handling 先前沒有作用，即時錄音的逐字稿一律遮蔽不雅字。本版起三個值都會生效：

譯文依處理後的逐字稿產生。此設定只適用即時錄音；檔案匯入的逐字稿保留原文。

修正：無法翻譯的句子改回錯誤碼

部分含辱罵、威脅等內容的句子，先前可能收到與原文無關的譯文。本版起這類句子改回 llm_content_filtered，與既有的「內容無法翻譯」處理相同。適用即時錄音、廣播、檔案匯入與重新翻譯；重新翻譯時該句不計費。

文件更新

• 摘要自訂中 profanity_handling 的值更正為 mask／remove／show（先前誤寫為 removed、raw）。

V1.18.0

2026-09-27

行為變更：長時間沒有語音時自動結束錄音

即時錄音連續 15 分鐘（預設）沒有偵測到語音時會自動結束，避免忘記停止的錄音持續計費。

• 結束前約 2 分鐘送出預警 stt_silence_warning（錄音照常進行，辨識出文字或恢復錄音就重新計時）；到期送出 stt_silence_timeout，接著照常收尾、收到 task_complete。
• 暫停中、斷線等待續接的期間與廣播不計時。
• 可用 start 的 silenceTimeoutSeconds 調整門檻或關閉（0），見 長時間沒有語音時自動結束。

行為變更：整場沒有收到音訊的錄音

整場沒有收到任何音訊的即時錄音，先前不會收到 task_complete，約 2 小時後才被標為失敗。本版起會收到帶 noAudio: true 的 task_complete，錄音立即標為 failed 並送出 recording.failed（failure_source 為新的值 no_audio）。這筆錄音沒有逐字稿與音檔。

行為變更：廣播預備階段的時間上限

預備階段累計達上限（預設 30 分鐘）時，這一場會自動結束：到期前約 2 分鐘送出預警 broadcast_standby_warning，到期時送出 broadcast_standby_timeout 與 status: "ended"。預備階段沒有錄音，不計費。見 預備階段的時間上限。

行為變更：start 的廣播參數檢查

broadcast_phase 只接受小寫的 standby、live（空字串視同 live）；broadcast_token 只能搭配 type: "broadcast"。不符時回 invalid_parameter，錄音不會開始。

行為變更：主講者斷線後重新開播（接管）

主講者在寬限期內用同一個 broadcast_token 重新開播時，新連線的 broadcast_recording_ready 會帶新的 task_id，同一場廣播分成兩筆錄音、各自送出完成通知。先前兩段共用同一筆錄音，後面的內容會覆蓋前面的。

行為變更：全文重翻支援分段續翻

長逐字稿可帶 segmented=1 分段續翻；沒有分段而逐字稿太長時，會在串流開始前回 HTTP 422 retranslate_segmentation_required，不扣點。詳見 重新翻譯 SSE。

行為變更：匯入失敗與失敗說明

• 同一筆匯入失敗只送出一次 import.failed，處理期間維持 processing。
• failed 是最終狀態，之後不會再收到同一筆的 import.completed；長時間沒有開始處理的匯入會標為 failed（PROCESSING_TIMEOUT）。
• 匯入的 error_message 與 recording.failed 的 error 改為固定說明，不再帶出內部訊息；錯誤碼不變。

行為變更：觀眾端的頻率限制

• 廣播觀眾頁與密碼驗證改為依頻道計算（每分鐘約為頻道最大觀眾數的 2 倍，最少 200 次），不再是每個來源 IP 每分鐘 10 次；同一網路下大量觀眾同時進場不再容易收到 429。
• 密碼錯誤過多會暫時鎖定（同一來源 5 分鐘內錯 30 次，或同一頻道 5 分鐘內累計錯 100 次），鎖定期間即使密碼正確也回 429；同一來源查詢不存在的頻道過多也會暫時回 429。見 頻率限制。
• 浮動字幕觀眾換票改為同一場、同一來源每分鐘 30 次；同一來源分享連結無效過多時會暫時回 429。

行為變更：匯入的辨識模式與檔案格式

• 上傳匯入時 recognition_mode 帶 multi_language 或 multi_channel，改回 HTTP 422 import_recognition_mode_unsupported（data.details.supportedModes 列出可用模式）。先前 multi_language 會被受理、之後處理失敗，multi_channel 則回 validation_failed。
• 副檔名與實際內容格式不符時（例如檔名是 .mp3、內容是 WAV），改依實際內容處理，不再因此失敗。

行為變更：摘要生成的完整性

適用 Ad-hoc 摘要與重新生成摘要：

• 生成時間過長時，會在處理時間上限內回傳已完成的部分，done 帶 truncated: true 並照常計費；先前可能既收不到 done 也收不到 error。
• 串流中途停住或沒有正常結束時，改送 error（sse_summary_regeneration_failed），不儲存、不計費；先前可能把不完整的摘要當成完整結果交付。

其他行為變更

• 合併語者時，目標語者原有的句子若顯示名稱因合併而改變（例如來源語者的自訂名稱轉給目標），也會改用合併後的名稱並列入 affected_sids；REST 與 WebSocket 皆同。
• 服務重新啟動或更新時，正在等待續接的錄音會直接收尾並照常保存；之後續接會收到 resume_token_invalid。
• 廣播的 current_recording_id 只在直播中有值，為這一次開播的錄音；預備階段或未在直播時為 null。

修正

• 開播之後才加入的廣播觀眾，會看到預備階段的內容。
• 由預備階段轉為直播的廣播，最多多計 1 分鐘；本版起從開播那一刻起算。
• 直接開播的廣播，broadcast_recording_ready 偶爾比 session_started 早送達。
• 完整音檔有時少了錄音最結尾的一小段。
• 使用 audio_format: "webm" 的錄音，中途更換錄音裝置後，之後的聲音不再遺失。
• 服務短暫異常恢復後，進行中的錄音照常計費；異常期間的用量也會在恢復後補計。

新增錯誤碼

客戶端建議

• 認得 stt_silence_warning 與 broadcast_standby_warning：錄音照常進行，不是結束。
• 長時間可能沒人說話的場合（例如會議室），start 請帶 silenceTimeoutSeconds: 0。
• 收到帶 noAudio: true 的 task_complete 時，不要讀取逐字稿。
• 廣播接管後，錄音 ID 以新連線的 broadcast_recording_ready 為準。
• 長逐字稿的全文重翻請帶 segmented=1，並依 done 的 truncated 繼續下一段。
• 觀眾端收到 429 時，依 Retry-After 的秒數等待後再試，不要立即重試。
• 匯入的 recognition_mode 只用 single 或 multi_speaker。
• 摘要串流以 error 結束時，捨棄已收到的片段；done 帶 truncated 時，提示使用者摘要不完整。

文件更新

• 錯誤碼參考補上匯入失敗時會出現的五個錯誤碼與 invalid_parameter。
• 多聲道「每一路靜音也要持續送」的說明更正：單一聲道沒有聲音不會結束錄音。
• 觀眾端與浮動字幕觀眾換票的 429 補上錯誤碼 too_many_requests，浮動字幕觀眾換票的 403 補上錯誤碼 invalid_share。

V1.17.0

2026-09-24

新增：摘要翻譯端點

新增 POST /api/v1/sse/summary/translate，可以把請求帶入的摘要文字翻譯成指定語言。這個端點不綁定錄音，翻譯結果也不會儲存，計費為每 200 字元 0.1 點。詳細規格請見摘要翻譯。

修正：重新翻譯摘要

• 摘要重新生成為其他語言之後，再重新翻譯時可能沒有翻譯，直接回傳原文。本版已修正。
• 重新翻譯較長的摘要時，譯文可能只有前面一部分。本版已修正。

修正：多聲道斷線續接

多聲道模式在斷線續接後，各聲道不再產生辨識結果，續接後的錄音也沒有保存。本版已修正。

修正：互譯模式說到一半的句子遺失

• 手動模式放開說話鍵時，最後一段還沒辨識完成的內容會遺失。本版已修正，會併入該句的定稿。
• 手動模式說話中改語速或連線恢復時，當下那一段會遺失；說話中結束錄音時，整句會遺失。本版已修正。
• 自動模式暫停後恢復，暫停前說到一半的句子會被下一句覆蓋。本版已修正，暫停當下就會以 is_final: true 送出。
• 以空白分字的語言（例如英文），手動模式合併的段落之間沒有空白。本版已修正。
• 單人與互譯模式在改語速等操作的瞬間，偶爾會重複出現同一句，或已作廢的句子又出現。本版已修正。

修正：停止錄音時最後一句可能不見

按下 stop 時，最後一句如果還沒辨識完成，先前不會進入逐字稿。本版已修正：停止時會先等辨識服務處理完最後一句（通常約 1 秒，最多約 3 秒）再收尾；等不到時，以畫面上最後的辨識結果作為該句內容。互譯模式的 pause、手動模式的 stop_speaking 也同樣會先等。

修正：收尾較久時可能收不到 task_complete

stop 之後的收尾（標題、摘要、上傳）較久時，連線可能在送出 task_complete 之前被關閉。本版已修正。另外，標題與摘要改為同時產生，stop 到 task_complete 的等待時間縮短。

修正：服務維護期間剛結束的錄音可能沒有完整保存

服務維護期間，剛結束或剛斷線的錄音，逐字稿、完整音檔與完成通知有時來不及處理，錄音會停在處理中，之後被標成失敗。本版已修正：服務關閉前會先把這些收尾做完。

修正：串流錯誤不再帶出系統內部訊息

匯入進度 SSE與 TTS SSE 串流發生非預期錯誤時，details.original_error 一律為 Service error，與其他串流端點一致；錯誤碼不變。

修正：TTS SSE 串流的錯誤訊息

TTS SSE 串流的 tts_error 事件，message 原本會送出內部識別字串，現在改為標準英文訊息（例如 TTS synthesis failed）；error 欄位的錯誤碼不變。文件中「該句缺少翻譯」的錯誤碼更正為實際送出的 tts_translation_not_found，行為未變。

行為變更：服務即將關閉時的連線處理

• 收到 service_shutdown 後，沒有在錄音的連線會在約 2 秒後關閉。
• 錄音中的連線可以把這一場錄完，stop 後照常收到 task_complete，之後連線才會關閉。

行為變更：停止、暫停與同時錄音名額

• status: "ended" 一定在 task_complete 之前送出。
• 同時錄音名額改在送出 task_complete 時釋放：收到後即可開始下一場錄音。
• stop、互譯模式的 pause、手動模式的 stop_speaking，回應會延後約 1 秒（最多約 3 秒）。

客戶端建議：判斷錄音完成

• task_complete 要等標題與摘要生成完成，通常數秒到數十秒，最長約 8 分鐘。判斷錄音是否完成，建議同時支援 Webhook 或 REST 查詢，不要只依賴這個事件。

行為變更：重新翻譯摘要

• 譯文不完整時，done 會帶 truncated: true。
• 一次請求的處理上限約為 230 秒，翻譯途中停頓超過 60 秒會送出 error。逾時的 details.original_error 為 Translation timed out，原本是 Service error。
• 摘要較長時，串流有時會一次送出較大的段落，段與段之間也可能停頓數秒。

客戶端建議：摘要翻譯

• 收到 truncated: true 時，譯文並不完整，請不要當成完整結果保存。
• 如果要逐字呈現譯文，請在客戶端做平滑處理。

文件更新

• segment_discarded 的 reason 說明補上例外：斷線續接時，channel_status 用 reconnect，segment_discarded 用 resumed。
• start_speaking 更正：已在說話中再次呼叫時，會先結束上一句再開始新的一句，不會回錯誤。
• segment_discarded 補充：互譯手動模式也不會收到本事件。
• task_complete 補充：與 status: "ended" 的先後、要等標題與摘要、名額釋放時點、完成判斷建議。
• pause、stop、stop_speaking 補充等待最後一句的說明。
• 計費說明補充暫停與斷線期間的計費：暫停期間照常計費，斷線等待續接的期間不計費。
• 計費說明補充多聲道的路數採計：分鐘中途新增、下一次扣點前又停用的聲道補計一次；分鐘開始時已扣過點的聲道，停用後不會再計費。

V1.16.5

2026-09-21

新增：摘要事件帶出 summary_language

以下事件新增 summary_language（相容新增）：

判斷摘要本身的語言，請以 init_summary 的 summary_language 為準（沒有摘要時，它可能與 init_metadata 的同名欄位不同）。

修正：匯入任務的摘要語言

已產生摘要的匯入任務，任務列表與 init_metadata 的 summary_language 原本為 null。本版已修正，既有任務一併更正。

文件更新

• init_metadata 的 summary_language：錄音時未指定摘要語言，值一般為第一個轉錄語言（互譯模式有指定 active_language 時為該語言），不是 null。只有沒有摘要的任務可能為 null。
• 重新翻譯摘要（GET /api/v1/sse/retranslate/summary/{taskId}）的結果不會儲存。要以其他語言保存摘要，請使用重新生成摘要的 POST 端點（會計費）。

V1.16.4

2026-09-17

匯入額度預檢會回報「今日用量已滿」

POST /api/v1/imports/check-quota 原本只看點數與方案，當日用量已滿時仍回 allowed: true、實際上傳才被擋。本版起會回 allowed: false ＋ reason: "plan_daily_limit_reached"，與上傳被擋時的錯誤碼同名，可直接對應。

注意：allowed 為 false 時，儲值不是所有情況的解法——今日用量已滿要等隔日重置、方案不含匯入要升級方案。請依 reason 給不同提示，見 匯入 API 參考。

額度不足的錯誤新增 budget_scope

auth_quota_exceeded 與 stt_quota_exceeded 的 details 新增 budget_scope，說明同一則訊息裡的 remaining_budget 屬於誰。相容新增，既有欄位未變動。

重要：remaining_budget 是發出這次請求的 API Key 可動用的額度，不是終端使用者的餘額。 代其他使用者呼叫本服務的整合方，請不要把這個數字直接顯示給終端使用者。各值的意義見 錯誤碼參考。

V1.16.3

2026-09-17

計費修正：無法正常運作的聲道不再採計

多聲道錄音中，若某一路的音訊在結算當下無法被接收、因而不會產生逐字稿，該分鐘不再計入這一路；先前仍會計費。採計口徑（含第一分鐘與未送出音訊的處理）見 計費說明。

行為變更：廣播 Token 僅限所屬帳戶使用

以不屬於本帳戶的 broadcast_token 開播會收到 broadcast_token_invalid。同一帳戶下的不同 API Key 不受影響。

新增錯誤碼：task_already_processing（409）

同一筆任務仍在處理中時，POST /api/v1/tasks/{taskId}/retry 回 409 task_already_processing，任務狀態不變；稍候再送出同一個請求即可。先前這種情況會回 200，但任務不會被重新處理。

修正：重新生成摘要後的摘要語言

不指定 language 重新生成摘要時，任務資料記錄的摘要語言未跟著更新，與實際摘要內容不一致。本版起兩者一致。

V1.16.2

2026-09-16

文件更新：廣播 task_id 的取得方式

廣播場次的 task_id 以 broadcast_recording_ready 事件帶回的值為準； session_started 帶的是連線階段的初始值，用它查詢會查無資料。 兩種開播方式都會收到此事件：經預備階段轉正式開播，或 start 時直接指定 broadcast_phase: "live"（預設值）。 行為未變，本版僅補齊說明。

V1.16.1

2026-09-16

文件更新：計費分鐘數的邊界

即時錄音的計費分鐘數，每個分鐘邊界後有 1 秒寬限：錄 60.5 秒計 1 分鐘，錄 61.5 秒計 2 分鐘。 計費行為未變，本版僅補齊說明。

V1.16.0

2026-09-15

行為變更：即時錄音改為每一分鐘開始時扣點

即時錄音（廣播除外）原本在每一分鐘用完後扣點，結束時再把未滿一分鐘的部分以一分鐘計。 本版起改為在每一分鐘開始時扣點：

• 開始錄音時先扣第一分鐘，扣點完成後才會收到 session_started
• 之後每一分鐘開始時，扣下一分鐘
• 結束錄音時不再另外扣點

每場的計費分鐘數仍依「未滿一分鐘以一分鐘計」計算。先前部分錄音實際計費的分鐘數比這個規則少一分鐘， 本版起一律依規則計算，因此同樣長度的錄音可能比先前多計一分鐘。

錄音中開關功能、增減聲道或翻譯語言時，費率自下一分鐘起調整。多聲道的路數採計方式見 計費說明。

行為變更：可用點數不足一分鐘時，錄音無法開始或繼續

• 開始錄音時：錄音不會開始，收到 auth_quota_exceeded，details.remaining_budget 為最近一次結算時的可用點數。 連線不會中斷，儲值後可直接再次送出 start
• 錄音中：在下一分鐘開始前結束錄音，收到 stt_quota_exceeded；已錄製的內容照常保存
• 不足的那一分鐘不會扣點，也不會先扣掉剩下的點數

開始錄音時若暫時無法確認可用點數，會收到 auth_service_error，錄音不會開始，請稍後再試。

新增：summary_insufficient_credit 錯誤碼

下列情況不產生摘要，改送 summary_error，錯誤碼為 summary_insufficient_credit：

• 錄音因可用點數不足而結束
• 正常結束時，可用點數不足以支付摘要費用

逐字稿與錄音照常保存，儲值後可透過重新生成摘要取得。

行為變更：吃到飽方案的用量上限在每一分鐘開始前判斷

• 單次錄音上限、使用時數門檻與每日硬上限，都在每一分鐘開始前判斷；達到時下一分鐘不會開始，也不計入用量
• 開始錄音時若今日用量已達上限，會直接收到 daily_limit_reached，錄音不會開始
• 進入限制窗口後，每段可連續錄音的時間與方案設定的間隔相同（先前會多 1 分鐘）
• 同一把 API Key 同時進行多場錄音時，達到定期中斷的門檻後，每一場都會在各自的下一分鐘開始前中斷 （先前每次只中斷其中一場）
• GET /api/v1/me/plan 的已使用分鐘數，在每一分鐘開始時就計入該分鐘

行為變更：credit.exhausted 的送出時機

即時錄音因可用點數不足一分鐘而無法開始或繼續，且帳戶餘額不足以支付該分鐘時，也會送出 credit.exhausted， 此時 balance 可能大於 0.0。若只是 API Key 的專屬額度不足、帳戶餘額仍足以支付，則不會送出，與先前相同。

Bug 修正：同一條連線連續錄音時的問題

在同一條連線上結束一場錄音後再開始下一場，可能發生下列情況：

• 下一場的摘要費用把前面場次的逐字稿字數一併計入；即使該場沒有產生摘要，也可能被收取摘要費用
• 前一場開啟過語音合成，下一場即使沒有開啟，也以含語音合成的費率計費
• 前一場使用自訂摘要設定時，下一場結束後錄音可能沒有保存
• 多聲道錄音：前一場的音檔未能完整保存時，下一場的錄音也可能無法保存
• 重新開始後浮動字幕沒有啟動
• 前一場的點數不足或方案限制通知，中斷了下一場

本版皆已修正。

Bug 修正：錄音被結束後立即重新開始，上一場可能沒有保存

錄音因點數不足、方案限制、用量上限或長時間沒有聲音而結束後，若在同一條連線上立即送出 start， 上一場的錄音可能沒有保存，新的一場也可能沒有逐字稿。

本版起會等上一場處理完成（收到 status: "ended"）後才開始新的一場；視摘要長度， session_started 可能延後數秒到數十秒。以新的連線開始錄音不受影響。

行為變更

• 送出 stop 後、收到 status: "ended" 之前（包含錄音被結束、仍在處理中時），帶 resume token 重新連線會收到 resume_unavailable，不會接回已經結束的錄音
• 上一場仍在處理中時送出 broadcast_go_live，會收到 session_not_started
• auth_quota_exceeded 與 stt_quota_exceeded 的 details.remaining_budget，改為最近一次結算時的可用點數
• 錄音因點數不足而結束時，stt_quota_exceeded 只會送出一次
• 錄音結束後，不會再收到該場的點數不足或方案限制錯誤
• 連線中斷期間錄音被結束時，同一把 API Key 的併發錄音名額會隨即釋放（先前約 3 分鐘後才釋放，期間可能收到 concurrency_limit_reached）

客戶端建議

• 開始錄音可能因點數不足收到 auth_quota_exceeded：連線不會中斷，儲值後直接重新送出 start 即可
• 監聽 summary_error 的 summary_insufficient_credit，告知使用者因點數不足未產生摘要
• 錄音被結束後在同一條連線重新開始時，session_started 可能延後，請不要視為逾時
• 上一場仍在處理中時，pong 也可能延後；請保留足夠的等待時間，不要只因暫時沒有收到 pong 就判定斷線
• 收到 resume_unavailable 時，若使用者已經結束錄音，請不要自動開始新的錄音

文件更新

• WebSocket start 的錯誤碼表補上 auth_quota_exceeded、daily_limit_reached、auth_service_error；broadcast_token_invalid 的 HTTP 狀態碼更正為 401，與錯誤碼參考一致
• broadcast_go_live 的錯誤碼表補上 session_not_started
• 斷線續接範例：使用者已結束錄音時，續接失敗不再自動開始新的錄音
• 心跳說明補充上一場處理中時 pong 可能延後
• 音檔匯入的 stt_quota_exceeded 說明更正為可用點數不足以支付本次匯入
• 摘要客製指南的事件範例更正為實際的訊息格式（type 為 voice-translation，以 data.action 區分事件）

V1.15.10

2026-09-12

Bug 修正：內容無法翻譯時，重新翻譯回報成功卻沒有譯文

重新翻譯（全文、單句、摘要）遇到無法翻譯的內容時，會回報成功、譯文空白； 全文重翻還會照常計費，並覆寫該語言原本的譯文。

本版起改為回報失敗：原本的譯文保留，失敗的句子不計入更新數、也不計費。

Bug 修正：多個作業同時進行時，成果可能遺失或被誤計費

同一份錄音同時進行多個作業（例如同時重翻成不同語言，或一邊重翻一邊修改說話者名稱）時， 可能出現「成果沒有保留卻照常計費」，或「沒有實際消耗卻帶出計費欄位」的情形。

本版起這些情形會明確回報失敗，本次不計費。

行為變更

• 重新翻譯可能回傳 llm_content_filtered（severity 為 warning）；其餘翻譯失敗回 sse_translation_failed，摘要重翻為 sse_summary_translation_failed
• 逐字稿儲存失敗時，重新翻譯、摘要儲存與說話者操作一律回報 storage_upload_failed 並中止，之後不會收到 done
• 同一份逐字稿同時有多個變更時，後到的回 transcript_revision_conflict（409）
• done 只在確實計費時帶出 characters_billed / charged / billed
• 以顯示名稱指定說話者、且該名稱對應到多位時，回傳 speaker_name_duplicate
• 只有空白的譯文不再出現在匯出檔與語音合成中

客戶端建議

• llm_content_filtered 重試無效，請改寫原文；依 severity 過濾事件時請勿濾掉 warning
• 收到 transcript_revision_conflict 表示當下另有變更在進行，直接重試即可
• 請以 billed 判斷本次是否計費；代呼叫並向終端用戶計價的整合方尤其不要從其他欄位推算

V1.15.9

2026-09-10

Bug 修正：連線中斷後恢復，說話者的名稱可能掛到別人身上

說話者辨識（多人模式）下，錄音中途若發生連線中斷後恢復，先前重新命名過的名稱 可能被套用到另一位說話者身上；先前設定的合併也可能把兩個不同的人併成同一位。 兩種情況都不會有任何提示。

本版已修正：恢復後新出現的說話者會配發新的編號，不會沿用先前的名稱與合併設定。

行為變更：說話者編號不再保證從 1 開始或連續

說話者編號在整場錄音內唯一，但不保證從 1 開始、也不保證連續。 連線中斷後恢復、以及廣播由預備進入直播時，後續出現的說話者會配發沒用過的新編號。

rename_speaker 與 merge_speakers 只對當前已辨識出的說話者有效。恢復後若確認是同一位， 請重新合併一次；若目標尚未命名，合併會把來源的名稱帶過去。

廣播由預備進入直播時，預備階段設定的說話者名稱不保留。

單人、互譯與多聲道模式不受影響。

客戶端建議

• 若您的應用假設「編號從 1 開始且連續」或「同一人整場同號」，請改為以收到的 speaker_id 為準
• 恢復後要接續同一位說話者，請用 merge_speakers；沿用先前的名稱去 rename_speaker 會收到 speaker_name_duplicate
• 廣播主控端收到階段變更為 live 時，請清空自行累積的說話者清單

V1.15.8

2026-09-09

Bug 修正：互譯切換模式時，說到一半的句子會消失

互譯模式下，在說話途中切換自動／手動模式或按下說話鍵，該句會以新的句子編號重新出現， 原本的編號不再有任何後續，該句也不會出現在逐字稿裡；後續講的那句還可能拿不到自己的譯文。

本版已修正：說到一半的句子會留在原本的編號上並正常結束，之後講的那句才拿新編號。

新增：segment_discarded 事件

調整語速、更換聲道語言、進入直播、斷線續接、暫停後恢復時，若當下正有一句話說到一半， 該句無法保留。先前這些情況不會有任何通知，該句因此沒有結束的訊號。

本版起會送出 segment_discarded，告知該句子編號不會再有任何後續，並以 reason 指出 對應的操作；多聲道另帶 channel_id。浮動字幕觀眾同樣會收到。

行為變更

重送目前已生效的對話模式，不再影響進行中的句子；模式變更通知照常回覆。

客戶端建議

• 收到 segment_discarded 時，把對應的句子從未完成狀態移除
• 互譯自動模式不會收到本事件；該模式下說到一半的句子會正常結束，內容保留在逐字稿中
• 收到 set_speaking_speed_failed 時，該次操作仍可能已送出 segment_discarded
• 欄位與完整 reason 值域見 segment_discarded

V1.15.7

2026-09-08

Bug 修正：重新翻譯有時回傳的不是譯文

事後重新翻譯時，較短的句子可能不會被翻譯，而是得到一段與該句內容相關的說明文字， 並被存為該句的譯文。

本版已修正。受影響的句子重新翻譯一次即可取得正確譯文；單句重新翻譯不計費。

文件更新：zu-ZA 語言名稱更正

支援語言清單中 zu-ZA 的中文名稱更正為「祖魯語」。語言代碼與支援範圍不變。

V1.15.6

2026-09-06

Bug 修正：上傳音檔的 202 回應，progress 回了 null

POST /api/v1/imports 上傳成功時回傳的 progress 應為 0，實際卻是 null。 同一筆匯入改用 GET /api/v1/imports/{importId} 查詢時又是 0，兩處不一致。

影響：對回應做嚴格結構驗證的客戶端，會把一次成功的上傳判定為失敗， 因而拿不到 import_id、也收不到完成通知。使用者重試一次就多一筆實際會跑完的匯入與點數消耗。

本版起 progress 在 202 回應中一律為 0，與文件及查詢端點一致。

Bug 修正：建立廣播頻道的 201 回應，三個計數欄位回了 null

POST /api/v1/broadcasts 建立成功時回傳的 peak_viewers、total_viewers、duration_ms 應為 0，實際卻是 null。改用 GET /api/v1/broadcasts 或 GET /api/v1/broadcasts/{broadcastId} 查詢同一個頻道時又是 0。

症狀與上一項相同：對回應做嚴格結構驗證的客戶端，會把一次建立成功判定為失敗。 使用者重試就會留下多個實際可用的頻道，各佔一個 token。

本版起這三個欄位在 201 回應中一律為 0。建立頻道本身不消耗點數， 既有頻道與其統計數值不受影響。

文件更新：task_id 在上傳成功當下就有值

task_id 先前被描述為「處理完成後才有值」，且 POST 與 GET 的回應範例都寫成 null。 實際上上傳成功（202）當下 task_id 就已經產生，不需等到處理完成。

客戶端可以在收到 202 時就導向該筆任務，不必為了取得 task_id 而輪詢。 文件的範例與欄位說明皆已更正。

客戶端建議

無需修改整合方式。若你曾因 progress 或廣播的三個計數欄位為 null 而放寬驗證， 可以改回要求整數；若你原本等到處理完成才使用 task_id，現在可以提前到上傳成功當下。

V1.15.5

2026-09-04

Bug 修正：講了轉錄語言清單以外的語言時，部分譯文是未翻譯的原文

指定多個轉錄語言、但實際講了清單以外的語言時，某個翻譯語言的譯文可能直接顯示原文。

以轉錄語言 zh-TW、id-ID 搭配翻譯語言 en-US、zh-TW、id-ID 為例：講英文時， 印尼文譯文會顯示英文原文。本版已修正。

行為變更：多個轉錄語言時，每份譯文一律經過翻譯

指定多個轉錄語言時，每個翻譯語言的譯文都會實際翻譯產生，即使原文語言與該翻譯語言相同。 這類譯文的用字可能與原文略有不同（語意相同）。

只指定單一轉錄語言的場次不受影響：原文語言與翻譯語言相同時，該份譯文仍直接沿用原文。

計費方式不變：翻譯依「翻譯語言數」計算，與譯文是否實際翻譯無關。

客戶端建議

無需修改整合方式。實際會講到的語言，請都放進轉錄語言清單。

V1.15.4

2026-09-04

Bug 修正：部分目標語言的譯文是未翻譯的原文

同時指定多個轉錄語言時，其中某個目標語言的譯文可能直接顯示原文，而不是翻譯結果。

以轉錄語言 en-US、zh-TW、id-ID 搭配相同三種翻譯語言為例：說印尼文時， 英文譯文會顯示印尼文原文，中文譯文則正常。本版已修正。

Bug 修正：互譯的語言標記與說話者標記

互譯在部分語言組合下（例如英文與印尼文），語句可能被標記成另一方的語言， 說話者標記與逐字稿的語言標記也會跟著錯。本版已修正。

Bug 修正：匯入指定多個轉錄語言時的譯文

匯入時若指定多個轉錄語言，且翻譯目標語言包含其中第一個語言，該語言的譯文可能是 未翻譯的原文。本版已修正。

行為變更

部分語言組合下（例如同時指定英文與印尼文），原文語言與目標語言相同的譯文， 用字可能與原文略有不同（語意相同）。先前這類譯文會逐字沿用原文。 只指定單一轉錄語言的場次不受影響。

客戶端建議

無需修改整合方式。若您的應用會以「原文與譯文是否完全相同」判斷語句是否已翻譯， 請留意上述變更。

V1.15.3

2026-09-03

Bug 修正：模糊詞校正可能改壞原本正確的內容

fuzzy_correction 的錯誤變體若以拉丁字母書寫，先前會套用到更長單字的一部分， 把原本就正確的內容改壞。

以術語 Remote View、並把 Emote View 列為錯誤變體（開啟 case_insensitive）為例： 逐字稿中原本正確的 Remote View，其中的 emote View 會被視為命中而替換， 結果變成 RRemote View —— 開頭多出一個字元。

本版起，以拉丁字母書寫的錯誤變體只會套用在完整單字上。 中文、日文、韓文的比對範圍不變。

Bug 修正：校正後緊接的標點或空白會消失

校正後緊接在變體之後的標點或空白也會一併消失，且不會有任何提示：

中文標點同樣會被吃掉（語遮分離，很重要 的逗號）。本版起一律保留。

行為變更

同音校正的常見詞保護不再被相鄰的空白繞過。 先前當錯字的前後剛好有空白時， 常見詞保護會失效、該錯字仍被校正；沒有空白時則不會。同一個詞的結果取決於旁邊有沒有空白。

本版起兩種情況一致，一律套用常見詞保護。少數原本會被校正的常見詞因此不再校正 —— 若確實需要校正這類詞，請在 fuzzy_correction 中明確列出。

字庫設定中的詞，頭尾空白一律忽略。 先前帶頭尾空白的設定結果不一致， 其中一種還會連帶吃掉逐字稿的空白。本版已修正， 但也代表僅以空白區分的兩筆設定會被視為同一筆。

文件更新

• 字庫使用指南補上「拉丁字母以完整單字為單位比對」的說明
• 修正字庫使用指南中一個帶尾隨空白的錯誤變體範例（該寫法不會生效）

客戶端建議

無須調整既有整合。字庫設定格式、數量限制、錯誤碼與衝突代碼皆未變更。 若字庫中登記過「較短的拉丁字母寫法」並倚賴它涵蓋較長的單字（如以 wafer 涵蓋 wafers）， 請把兩種形式分別登記。

V1.15.2

2026-09-03

行為變更

在錄音尚未開始、或已經結束後送出 stop，現在會回傳 session_not_started 錯誤。 先前這兩種情況完全沒有任何回應，客戶端只能等到逾時才知道操作沒有生效。

最常見的情境是重複送出 stop：第二次會收到此錯誤，而不是再一次的成功回應。 task_complete 仍然只在第一次成功停止後送出一次。若客戶端本來就把重複送出視為無害， 忽略這個錯誤即可。

文件更新

• stop 補上錯誤碼說明
• 多聲道的 add_channel、remove_channel、set_channel_language 補齊錯誤碼表中先前遺漏的項目

V1.15.1

2026-09-03

修正

• config 回傳 config_empty 時，錯誤訊息改為明確說明：空物件 {} 不視為有提供設定，並附上清空字庫的正確寫法
• 文件補上：config 被拒絕時回傳的是 type: "error"，而非 config_updated。客戶端需同時監聽 error 訊息，否則會誤判為無回應

錯誤碼與回應結構皆未變更。

V1.15.0

2026-09-03

Bug 修正：長會議的摘要內容被截斷

較長的會議在生成摘要時，摘要可能在中途停住、句子沒有寫完，而且不會回報任何錯誤 —— 串流照常結束、done 事件照常送出，客戶端無從察覺拿到的內容並不完整。錄音越長越容易發生。

本版起，一小時以上的會議也能完整輸出結構化紀要。

這與既有的 summary_fallback_level / summary_dropped_segments 是兩件不同的事。 後者代表輸入的部分段落被省略（摘要句子完整，但少了某段會議內容）； 本次修正的是摘要本身寫到一半停住。

新增功能

摘要不完整時會明確告知。 即席摘要（POST /api/v1/sse/summary）與重新生成摘要 （GET / POST /api/v1/sse/regenerate/summary/{taskId}）的 done 事件新增選填欄位 truncated：摘要未能完整產出時值為 true，摘要完整時此欄位完全不出現。

這是純新增、向後相容的欄位，舊有整合忽略即可。即使未來仍有極長的摘要無法完整產出， 客戶端也看得見。

行為變更

摘要輸入的字元上限由 100,000 提高為 200,000。 影響的端點：

• POST /api/v1/sse/summary 的 content
• GET / POST /api/v1/sse/regenerate/summary/{taskId} 的逐字稿
• 錄音結束時自動生成的摘要

先前逐字稿超過 100,000 字元的長時間錄音會直接收到 summary_text_too_long、 完全沒有摘要。新的上限對齊音檔匯入所支援的最長時長（10 小時）， 因此不會再出現「檔案匯入成功、卻沒有摘要」的情況。

摘要的字庫套用範圍擴大。 先前逐字稿較長時，字庫只有一部分會套用到摘要， 而且沒有任何提示。本版大幅放寬。即時翻譯的行為不變。

即席摘要的免費重新生成次數改為有上限。 同一個 idempotency_key 帶相同內容重送時， 先前會免費重新生成且無次數限制；本版起超過上限會回 429 too_many_requests。

免費重試是為了處理「已扣款但沒收到結果」的情況，正常一兩次就夠。要重新生成請改用新的 idempotency_key（會依費率重新計費）。首次的付費請求不佔用重試額度； 未產出任何內容的失敗也不佔用。額度以 24 小時為窗口計算。

客戶端建議

• 重要：請檢查你的用戶端逾時設定。摘要現在會完整生成，長會議的等待時間比以往長， 建議摘要相關的串流連線逾時至少留 5 分鐘。設得太短會在摘要完成前就中斷連線
• 先前因 summary_text_too_long 而沒有摘要的長錄音，現在可以重新生成
• done 事件新增了選填的 truncated 欄位（見上方「新增功能」）。舊有整合忽略即可， 但建議加上判斷，才知道拿到的是不是完整摘要
• 即席摘要若使用固定的 idempotency_key 反覆重送，現在可能收到 429。 正常的「一次請求一把新鍵」用法不受影響

文件更正

• guides/summary-customization.md 的「字元與長度限制」表先前未列出摘要輸入文字的上限， 已補上

V1.14.2

2026-09-02

Bug 修正：密碼保護的廣播頻道，觀眾無法連上字幕串流

觀眾輸入正確密碼、取得 viewer_access_token 後，連線觀眾字幕串流仍被拒（HTTP 401、broadcast_password_required）。本版修正後，密碼驗證通過即可正常連線。

• 觀眾在驗證密碼與連線串流之間切換網路（例如行動網路與 Wi-Fi、企業多線路出口），不會再導致連線被拒
• Token 有效期限維持 24 小時，verify 端點的回應欄位不變

Bug 修正：觀眾頻道資訊的 tts_languages 未正確回傳

GET /api/v1/viewer/broadcasts/{token} 的 tts_languages 先前可能固定回傳空陣列，導致客戶端誤判頻道未提供語音播報。本版修正後會正確回傳主講方已啟用的語音語言清單。欄位格式不變。

同一份回應中，tts_languages 的定義也一併澄清：它是主講方已啟用語音播報的語言，頻道未在直播中時為空陣列。先前文件寫的「否則從預設設定取得」並無對應行為。

行為變更：觀眾字幕串流的錯誤回應允許跨網域讀取

觀眾字幕串流（GET /broadcast/{token}/text）在拒絕連線時（401 / 404 / 503 等）的回應，現在與成功回應一樣帶有允許跨網域讀取的標頭。先前跨網域的客戶端在這些情況下只會得到一個跨來源錯誤，讀不到回應內容。

連線失敗的形態也隨之改變：先前跨網域的拒絕會被瀏覽器歸類為網路錯誤，EventSource 會依規格持續重連；本版起會直接終止連線（readyState 變為 CLOSED）、不再重試。以 EventSource 連線的客戶端若有自己的重連邏輯，請確認在這種情況下的行為符合預期。

客戶端建議：瀏覽器原生 EventSource 不會把回應主體交給頁面，因此仍然只看得到 onerror。若需要向觀眾顯示明確原因（例如 broadcast_password_required、broadcast_not_ready），請改以 fetch 讀取串流，或在連線前先呼叫 GET /api/v1/viewer/broadcasts/{token} 判斷頻道狀態與是否需要密碼。

文件更新

• 觀眾 API：viewer_access_token 移除來源位址綁定的描述；tts_languages 欄位說明更正
• 錯誤碼：broadcast_password_required 的 HTTP 狀態碼由 422 更正為 401（實際行為一直是 401）

參考文件：觀眾 API、觀眾即時字幕串流

V1.14.1

2026-09-02

文件更新：字庫驗證的請求大小上限

POST /api/v1/glossary/validate 先前未載明請求大小上限的實際數值，整合方無法在開發前評估自己的字庫是否送得進去。本版補上：

• 預設上限 2 MB（2,097,152 位元組）。仍建議以回應中的 details.max_bytes 為準，不要在程式中寫死
• 字庫超過上限時的分批方式：terminology 與 fuzzy_correction 必須在同一次請求中送出，translation_dict 可以單獨送

API 行為未變更，本版僅補齊文件。

**注意：若貴方已自行實作分批送出，請一併檢查。**將 terminology 與 fuzzy_correction 分成兩次送出時，部分衝突不會被偵測到，且回應不會有任何提示。

參考文件：字庫驗證 API

V1.14.0

2026-09-01

新增：字庫驗證 API

新增 POST /api/v1/glossary/validate，供字庫管理介面在存檔前檢查一份字庫有沒有格式問題或內部衝突。

字庫的多數設定問題不會產生錯誤訊息，只會在錄音或翻譯時安靜地產生非預期結果。最嚴重的一種是「某個錯誤變體同時是另一條規則的正確詞」——使用者正常說出那個詞也會被改成別的詞。此端點把這類狀況在使用者按下儲存的當下就指出來。

特性

• 免費，不扣點、不建立任何任務或錄音、不寫入任何設定
• 術語庫、模糊詞校正、翻譯字典三個區塊皆選填，給什麼驗什麼
• 每筆問題都附是第幾筆（語言代碼＋索引），管理介面可直接標記到條目
• 回應不含人語文案，由整合方依衝突代碼自行組句，語言與用詞完全自訂
• 頻率限制為每把 API Key 每分鐘 120 次，獨立配額，與其他端點分開計算
• 可從瀏覽器直接呼叫（支援跨來源請求）。注意：這代表 API Key 會出現在瀏覽器端，而同一把金鑰也能建立錄音、匯入音檔與消耗點數——內部後台可接受，公開頁面請改由貴方後端轉呼叫

注意：主機為即時服務網域（與 wss:// 同一個網域、協定換成 https://），與其他 REST 端點可能不同。

可偵測的八種衝突

同音檢查可關閉

八種衝突裡同音檢查最花時間，其餘幾乎立即回應。編輯過程中的即時提示可傳 check_homophones: false；真正存檔時再做完整檢查。

重要：同音檢查僅對中文有效，且不保證每次都能完成。回應的 homophones_checked 用來區分這兩件事：為 false 時代表沒有檢查完，不代表沒有衝突。存檔閘門請一併檢查此欄位。

新增：錯誤碼

行為澄清：config 是全有全無

先前文件描述 config 為「依序處理、失敗即中止，但排在前面的區塊已經生效」。實際行為並非如此：任一項失敗時三個區塊都不會套用，設定維持原狀。

對整合方的影響是變好的——收到錯誤時可以確定「什麼都沒變」，不需要再擔心處於半套用狀態。相關文件已全面更正。

行為澄清：變體碰撞不保證勝出者

先前文件描述同一錯誤變體對應多條規則時會依固定順序決定勝出者。實測結果與此描述不符，因此改為明確聲明：實際生效的是哪一條不保證，請勿依賴任何順序（包含登記順序）。這與新增的 variant_ambiguous 衝突代碼刻意不提供「哪一條會贏」的設計一致。

行為變更：TTS 語音目錄改為只列出可用的語言

先前 GET /api/v1/tts/voices 會列出全部 154 個 locale，但其中 13 個實際上無法使用——TTS 目標語言必須是翻譯輸出語言之一，而翻譯輸出語言限於轉錄語言清單，那 13 個不在其中。客戶查得到語音、設進 translation_languages 卻被拒絕。

本版起語音目錄只列出實際可用的語言，對外的語言數與語音數也一併改為可用值：

可能的影響：

• 以那 13 個 locale 之一查詢 GET /api/v1/tts/voices，現在會得到空的語音清單（先前會列出語音，但那些語音本來就無法用於合成）
• 以那些 locale 的語音查詢 GET /api/v1/tts/voices/{voiceName}/sample，現在回 404 tts_voice_not_found（與語音目錄不列出它們一致）

其餘語言不受影響。

受影響的 13 個 locale：bn-BD、ta-LK、ta-MY、ta-SG、ur-PK、su-ID、sr-Latn-RS、iu-Cans-CA、iu-Latn-CA，以及 4 個 zh-CN 方言（zh-CN-henan、zh-CN-guangxi、zh-CN-liaoning、zh-CN-shaanxi）。

行為變更：音檔匯入的時長上限開始真正生效

文件的「檔案限制」一直列著「最大時長 10 小時／最小時長 1 秒」，但先前只有選用的匯入預檢端點在檢查——直接上傳的音檔，長度不受任何限制。實務上 500 MB 的低位元率音檔可以超過 17 小時，會被完整處理並計費。

本版起，超出範圍的匯入會以 failed 事件結束，error_code 為新增的 import_duration_out_of_range。

可能的影響：若您目前有超過 10 小時（或短於 1 秒）的匯入，那些會開始失敗。請改用符合長度的音檔，或先切分後分次匯入。

超長音檔會先上傳成功、再以 failed 結束。要在上傳前就知道，請先呼叫匯入預檢端點。

行為變更：speaking_rate 超出範圍時會被夾制

TTS 的 speaking_rate 對外一直宣告有效範圍 0.5 ~ 2.0，但先前送出範圍外的值會原樣生效。本版起超出範圍時會自動調整至最接近的邊界值（低於 0.5 調成 0.5、高於 2.0 調成 2.0），讓實際行為與宣告的範圍一致。

可能的影響：若您目前送出的 speaking_rate 超過 2.0（或介於 0 與 0.5 之間），語速會變成邊界值。範圍內的值不受影響。

行為澄清：boost 超出範圍時兩條路徑不同

術語 boost 的有效範圍為 0.5 至 5.0。超出時：即時錄音與廣播會自動調整至範圍內且不產生提示；音檔匯入則直接拒絕（HTTP 422）。同一份字庫在兩條路徑得到不同結果，先前文件未載明。

文件更正

本版一併修正了下列與實際行為不符之處：

文件更新

• 字庫使用指南「注意事項」補齊六項先前未記載的狀況（錯誤變體遮蔽正確詞、同語言重複術語、加權值自動調整、錯誤變體等於自己的正確詞、字典同一來源詞重複、術語讀音相同），並逐項標示對應的衝突代碼
• 同指南新增「存檔前驗證字庫」一節
• 錯誤碼總表修正 invalid_json 的 HTTP 狀態描述（即時服務網域上的端點回 400，其餘回 422），並補上 invalid_action 在 REST 端點的用法
• 字庫使用指南補上語族比對規則、語言代碼留空的行為，以及 boost 的有效範圍

行為說明

• 數量超標時只回聚合結果：字庫的總筆數超過上限時，回應只包含數量問題本身，不再逐條列出內容問題、也不做衝突偵測。請先把數量調整到上限之內再重新驗證。
• 回報筆數有上限：衝突與格式問題各有回報上限，超出時 truncated 為 true。修正已列出的問題後重新驗證即可看到其餘的。

客戶端建議

• 字庫管理介面在儲存前呼叫一次本端點；valid 為 false 時阻止存檔並顯示問題條目
• 存檔閘門的判斷條件建議為 valid === true && homophones_checked === true
• 收到 auth_service_error（HTTP 500）時請稍後重試，不要更換 API Key——這與金鑰本身無關
• 通過本端點的驗證不保證音檔匯入會接受同一份字庫——匯入另有更嚴格的規則

參考文件

• 字庫驗證 API
• 字庫使用指南
• REST API 總覽

V1.13.1

2026-09-01

新增：完成事件帶出本次消耗量

下列端點的 done 事件新增三個欄位，讓整合方不必自行推算本次用量：

{
  "characters_billed": 12700,
  "charged": "1.3",
  "billed": true
}

• characters_billed：本次計費依據的字元數
• charged：本次依費率計算的消耗點數。此值反映用量——吃到飽方案已涵蓋的用量，此欄位仍回報消耗量
• billed：本次是否產生消耗

判斷本次是否計費，請一律以 billed 為準（billed 為 true 才是計費）。各端點的欄位出現時機不同：

• 重新翻譯全文、重新生成摘要：未產生消耗時（例如生成失敗）三個欄位皆不出現
• Ad-hoc 摘要：characters_billed 與 charged 恆會出現，而 billed 在免費重試 （同一冪等鍵＋完全相同的請求內容）與生成結果為空時為 false —— 此時本次並未計費

因此不可用「有無 charged」作為判準：Ad-hoc 摘要免費重試時 charged 仍有值，據此收費會多收。

不計費的端點不會帶這些欄位：重新翻譯摘要（/retranslate/summary/{taskId}）與單句重翻 （/recordings/{taskId}/entries/{sid}/retranslate）本就不計費，其 done 維持原樣。

客戶端建議

這是純新增欄位，既有整合不受影響，不需要任何修改。

代呼叫本服務、再向終端用戶計價的整合方，可直接採用 charged 而不必依字元數與費率自行推算， 避免兩邊計算基準不一致。若採用，請以 billed === true 作為是否計費的唯一判準——這條規則 涵蓋上列所有端點，不需要為個別端點寫例外。

V1.13.0

2026-09-01

變更：術語庫直接修正同音錯字

設定 terminology 後，逐字稿中讀音相同或相近、但用字不同的片段會被修正回術語的寫法，不需要事先列出可能的錯字。

這是行為變更，而且是雙向的：既有整合的逐字稿與譯文會開始改變。

• 以前漏掉的同音／近音錯字，現在會被修正（涵蓋範圍變大）
• 反過來，逐字稿中本身就是常見詞的錯字，現在不再被修正（見下方「常見詞保護」）。若你依賴這類修正，請把該錯字用 fuzzy_correction 明確列出

校正發生在轉錄當下，既有錄音不會回溯重算，本版之後建立的錄音才適用。

適用語言：僅中文（繁體與簡體皆可，兩者讀音相同因此互通）。日文、韓文、英文的術語不參與同音比對 —— 這些語言的錯字請用 fuzzy_correction 明確列出。

中英混合術語（如 CVD製程）只比對中文部分，英文原樣保留。

比對範圍：讀音相同與相近的寫法都涵蓋，包含前鼻音與後鼻音（jin／jing）、捲舌與不捲舌等口音差異。例如術語為「晶圓廠」時，逐字稿的「金圓廠」會被修正。

常見詞保護：若逐字稿中該片段本身就是常見詞（例如「金元」「反案」），即使讀音與術語相同也不會被改動 —— 這是為了避免正常語句被誤改。要強制修正這類錯字，請用 fuzzy_correction 明確列出：明確列出的錯字不受常見詞保護限制。

變更：fuzzy_correction 的 incorrect 對中文術語改為可省略

correct 是中文（含漢字）時，incorrect 可以整個不給 —— 系統會依讀音自動比對：

{ "fuzzy_correction": { "zh-TW": [{ "correct": "艾思通" }] } }

上例不必列任何錯字，「愛思通」「愛時通」「愛司東」「愛似通」都會被修正回「艾思通」。 只有讀音差距較大（如「愛自動」）或音節數不同（如「愛松」）的寫法才需要列進 incorrect。

這是放寬，既有整合不受影響（有帶 incorrect 的照常運作）。

注意：兩個條件缺一不可：語言要是中文，且 correct 要含漢字。不滿足時 incorrect 仍為必填 —— 那些情況省略了不會有任何效果，收下反而會讓你以為設定成功。日、韓、英文的錯字請明確列出。

同樣適用於音檔匯入：兩條路徑的判斷條件完全一致。

新增：config_updated 回報讀音相同的術語

字庫中若有兩個術語讀音相同（例如「公事包」與「公式包」），config_updated 會多一個選填欄位 homophone_conflicts：

"homophone_conflicts": [
  { "languages": ["zh-TW"], "terms": ["公事包", "公式包"] }
]

languages 列出被視為同一群的語言 —— 中文各地區代碼（zh-TW／zh-CN／zh-HK 等）在字庫比對上視為同一群，因此共用一筆而不是各報一次。

逐字稿出現讀音相同的第三種寫法時，系統只能改成其中一個，改成哪一個不保證。兩個術語本身都仍然生效，不確定的只有「沒登記過的同音錯字歸誰」。

這是警告不是錯誤：字庫照樣收下、config 照樣成功。若該組術語很重要，建議用 fuzzy_correction 明確列出錯字對應到哪一個術語。

錄音尚未開始時不會出現（此時語言清單還沒定案），與 inactive_languages 相同。

修正：segment_uploaded 的第一則事件缺少 segment_index

先前每場錄音的第一則 segment_uploaded 都沒有 segment_index， 極短片段（秒數捨入為 0）也會缺 duration_sec。

現在這兩個欄位在 segment_uploaded 事件中一定會出現。其他事件不受影響， 不會多帶這兩個欄位。

移除：config_updated 的三個選填欄位

• updated[] 不再出現 auto_generated_fuzzy_correction，只剩 terminology、fuzzy_correction、translation_dict
• auto_generated_fuzzy_correction_capped（值 variant_budget_exhausted）不再回傳
• auto_generated_fuzzy_correction_skipped（值 timeout）不再回傳

事件本身的形狀未變，terminology 與 fuzzy_correction 的設定方式、數量上限與錯誤碼都不變。

客戶端建議

• 若你的程式讀取上述三個欄位，請移除相關處理 —— 它們不再出現
• fuzzy_correction 在這三種情況仍然必要：
  1. 錯字本身是常見詞，會被常見詞保護擋下（例如「晶圓」被聽成「金元」）
  2. 錯字與正確詞讀音差距很大，例如外語品牌名被聽成音韻無關的詞
  3. 日文、韓文、英文的錯字 —— 這些語言不參與同音比對
• 若你先前為了涵蓋同音錯字而在 fuzzy_correction 列了大量中文錯字，多數現在可以省下來。但保留是安全的、有時反而更好 —— 明確列出的錯字不受常見詞保護限制，是唯一能確保某個錯字一定被修正的方式

參考文件

• 術語庫與模糊詞校正
• config action

V1.12.1

2026-08-27

變更：自訂摘要 prompt 的長度上限提高

custom 模式的自訂 prompt 從最多 2000 字元提高到 3000 字元。

適用於即時錄音的 summary_prompt、事後重新生成摘要與即時摘要的 prompt，以及音檔匯入的 summary_prompt。

長度以字元計算，中文一個字算一個字元。超過時回 summary_prompt_too_long。

注意：這是放寬，既有整合不受影響。但 prompt 愈長、指令愈多，實際被遵守的比例愈低 —— 上限提高不等於效果等比例提升。

V1.12.0

2026-08-27

翻譯字典改為依語言分組

翻譯字典的格式從「詞彙優先」改為「語言優先」，與 terminology、fuzzy_correction 一致。

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

先前的格式是一個扁平陣列，所有目標語言共用同一批來源詞，因而有兩個限制：

• 各語言無法擁有各自獨立的字典。若某個語言要管 500 個詞、另一個語言要管另外 100 個完全不同的詞，只能全部塞進同一個陣列、各自留空。
• 條目上限是所有語言共用的，語言愈多，每個語言能分到的詞彙愈少。

先前的格式繼續支援，既有介接不需要任何改動。 兩種格式送出同一份字典，結果完全相同。

適用於即時錄音、廣播與音檔匯入。

變更：字典條目上限改為每個語言各自計算

先前是所有語言合計最多 3000 條，現在是每個語言各自最多 3000 條。這是放寬，既有設定不會被擋下。

超過上限時回 config_too_many_dict_entries，回應中的 details 會指出是哪一個語言。

注意：總量會隨語言數成長。實務上先撞到的是單一設定訊息的大小上限（約 8 種語言各滿載即接近），而非條目數本身。

注意：不支援「清空整份字典」：送空的字典會被視為沒有帶這個設定項目。清空單一語言則可以（送該語言的空陣列）。

變更：續接時回傳的字典格式與送出時相同

resume_ok 中的 translation_dict，格式與你最後一次送出的相同——送先前的格式回先前的格式，送新格式回新格式。

變更：單次翻譯帶入的字典條目上限

同一段文字最多套用 100 個字典條目（先前無上限）。超過時優先套用來源詞較長的條目。

正常情況不會碰到：一段話通常只命中個位數個條目。這道上限擋的是「大量單字詞或極短來源詞讓幾乎每句都命中一大片」的情況。

變更：同一段文字的譯文更穩定

同一段文字先前每次的譯文可能略有不同，本版起結果固定。字典內容與行為不變，但譯文可能與先前有微幅差異。

不變的部分：目標語言仍為精確比對（en-GB 的譯法不會套用到 en-US）；大小寫規則（逐條 case_sensitive，預設不分大小寫）完全不動；字典仍屬盡力而為而非字面替換。

V1.11.1

2026-08-26

修正：翻譯字典未被保存，導致事後重翻與重新生成摘要不套用字典

即時錄音在 start 之後設定的 translation_dict，先前不會套用到下列功能：

• 事後重新翻譯（整份與單句）
• 單句重譯時的大小寫比對行為
• 重新生成摘要時的字典指引

症狀：同一份字典，即時翻譯時的指定譯法有生效，事後重翻卻沒有。 若你曾遇到這個落差，那個觀察是對的。

本版修正後兩者一致。這是行為變更：事後重翻與重新生成摘要的產出會開始套用字典， 與即時翻譯相同。既有錄音不追溯補寫，只影響本版之後建立的錄音。

廣播的字典先前同樣未被保存，本版一併修正。

新增：字庫使用指南

字庫的說明原本散落於各章節、以欄位規格的形式呈現，不易判斷各區塊的適用情境。本版新增字庫使用指南，涵蓋三種字庫（術語庫、模糊詞校正、翻譯字典）的作用階段與選用原則、術語的選擇與撰寫方式、生效時機、數量限制與對應錯誤碼，以及五項注意事項。

即時錄音、廣播、音檔匯入三種場景皆涵蓋在內——三者使用相同的字庫格式，差異僅在傳送方式（匯入的三個欄位為 JSON 字串而非物件）。

位置：功能指南 → 字庫使用指南。

文件變更：術語庫的文件說明已精簡

術語庫的說明、欄位表與範例已精簡為必要內容。

API 介面不變，客戶無需任何動作。 既有整合照常運作，不會因此收到錯誤或警告。

術語的辨識效果請透過「把術語登記在正確的語言代碼底下」來確保——詳見新增的字庫使用指南。

V1.11.0

2026-08-26

變更：翻譯字典上限提高到 3000 條

翻譯字典的條目上限由 500 提高到 3000。

字典大小不再影響每次翻譯的成本。

這是行為變更：字典條目的來源詞若與句子裡的實際寫法不完全相符，該條目不再套用。例如來源詞寫成複數形（wafers）而句子講單數（wafer），或來源詞是 IPEVO Inc. 而句子只講 IPEVO，都不會被套用。反向（來源詞較短、句子較長）仍會套用。

建議把來源詞設成實際會被講出來的最短形式。

變更：模糊詞校正的上限調整

新增：自動變體因額度用盡時的回報

config_updated 新增選填欄位 auto_generated_fuzzy_correction_capped。當術語庫要生成的變體超出剩餘額度時出現，值為 variant_budget_exhausted。

出現時代表自動變體已部分收下，不是整批失敗——已收下的規則照常生效。若要完整收下，請減少手動送出的變體數，或減少術語筆數。

變更：字庫上限改以回應中的 max 為準

字庫的各項上限（術語筆數、模糊詞規則數、翻譯字典條目數）現在可依環境調整。文件上的數字是預設值。

建議調整整合方式：不要把上限數字寫死。超限時的錯誤回應 details 一直都同時帶著 count（你送了幾個）與 max（實際上限），改讀 max 即可。既有整合不需要修改也能繼續運作 —— 這是建議而非破壞性變更。

變更：翻譯類錯誤的 provider 值

翻譯相關錯誤（llm_content_filtered、translation_service_unavailable 等）的 details.provider，值改為 llm_service。

先前的值不再使用，一律回 llm_service。

這是對外值變更：provider 一直只是 details 裡的除錯資訊，文件也從未把它列為可分支的列舉值，因此絕大多數整合不受影響。但若你的程式曾經比對過這個字串（例如據此分流告警），請改為比對新值，或改用 error_code 判斷——那才是設計上用來分支的欄位。

文件補正：config_updated 的選填欄位

config_updated 的欄位說明表此前只列了 updated 與 terminology_effective。以下欄位在 V1.10.1 就已存在、但只寫在更新紀錄裡，現已補進事件說明：

• unknown_languages／inactive_languages／inactive_dict_languages：字庫語言代碼的提醒
• auto_generated_fuzzy_correction_skipped（值 timeout）：自動變體生成未完成，本次不套用、既有規則保留，重送 config 有用
• updated[] 的第四個值 auto_generated_fuzzy_correction

與本版新增的 auto_generated_fuzzy_correction_capped 容易混淆，兩者差別是：capped 是「跑完了但放不下」（部分生效，重試無用），skipped 是「沒跑完」（完全沒變更，重試有用）。

V1.10.1

2026-08-25

修正：即時錄音的模糊詞校正未生效

即時錄音（WebSocket）設定的 fuzzy_correction 從未實際套用。送出 config 會收到 config_updated、斷線重連也會原樣拿回規則，但逐字稿、譯文、語音合成與摘要都不會套用校正——同一份字庫用在音檔匯入卻是正常生效的。

本版修正後，即時錄音與音檔匯入的校正結果一致。若你曾遇到「同一組字庫，匯入有用、即時錄音沒用」，那個觀察是對的。

這是行為變更：既有整合的逐字稿與譯文內容會開始改變（變成套用校正後的結果）。

變更：字庫依語系套用

三個字庫區塊改為依語言代碼決定適用範圍：

• 術語庫：只會用在與其語言代碼相符的辨識語言上。單一語言的情境（多聲道的每一路、多人語者分離、音檔匯入）只使用該語言的術語；多語轉錄與互譯則使用本次宣告的語言。
• 模糊詞校正：規則只套用在語言代碼相符的句子上——登記在 zh-TW 底下的規則不會動到英文句子。無法判定句子語言時，會套用全部規則。
• 比對採語言族群粒度：zh-TW／zh-CN／zh-HK 互通，en-US／en-GB 互通。

這是行為變更，且是靜默的：登記在本次未使用語言底下的字庫不會生效，而系統不會為此回報錯誤。請確認你送出的語言鍵與該場錄音實際使用的語言一致。

變更：字幕在句子結束時才套用校正

即時字幕的中間結果不套用模糊詞校正，句子結束（is_final）時才套用。介接方會看到字幕在句尾修正一次。

變更：字庫上限調整

三者皆為所有語言合計。

注意：翻譯字典的條目數會影響翻譯費用。實際套用的只有該目標語言有填譯文的條目，因此把譯文分散在不同語言可降低單次用量。

新增：字庫語言鍵的檢查回報

config_updated 新增兩個選填欄位，用來提醒可能不會生效的設定：

• unknown_languages：無法辨識的語言代碼（例如 zh、chinese）。這些字庫不會生效。
• inactive_languages：代碼合法但本場錄音沒有使用的語言。

兩者都是提醒，不會中斷設定。錄音尚未開始時不回報 inactive_languages（此時語言清單還沒定案）。

新增：字庫條目的欄位檢查

術語與模糊詞校正的條目改為在收下時檢查必填欄位與長度，不符時回 config_invalid_entry，details 指出是哪個語言、第幾筆、哪個欄位。此前這些問題會被靜默忽略。

移除：錯誤碼 config_terminology_locked

該錯誤碼從未被發出過——錄音進行中更新術語庫一直都是允許的。

修正：音檔匯入的部分語言未套用術語庫

部分語言的音檔匯入完全沒有使用術語庫（無錯誤、無提示）。本版修正後這些語言與其他語言行為一致。

修正：文件與實際行為不符之處

• 術語庫上限計的是術語筆數，boost 不佔用容量（此前文件在不同章節有兩種說法）。
• boost 在即時錄音不影響容量計算；音檔匯入的少數語言下會佔用額外名額。
• 翻譯字典的上限先前在指南寫「建議不超過 50 條」、在參考文件寫為硬上限，兩處已統一。

修正：翻譯字典的「大小寫完全相符」設定在事後處理未生效

字典條目的 case_sensitive 在事後重翻（全文重翻與單句重譯）被忽略——不論是否勾選，都以不分大小寫套用。即時錄音的逐句翻譯與摘要一直都有遵守，只有事後處理沒有。

本版修正後，同一筆錄音的三條路徑行為一致。

這是行為變更：若你依賴「勾了 case_sensitive 但事後重翻仍會套用」的既有行為，修正後大小寫不符的詞不再被替換——那才是該設定原本的語意。

變更：音檔匯入的摘要會套用翻譯字典

即時錄音的收尾摘要一直有依字典統一專有名詞譯法，音檔匯入沒有。本版起兩者一致。

摘要以來源語言輸出時字典無對應譯文，此時不注入（行為與即時錄音相同）。

變更：廣播公告與待機文字會套用翻譯字典

同一場廣播，逐句字幕依字典翻譯、公告與待機文字卻不套用，同一個專有名詞會出現兩種譯法。本版起一致。

未設定翻譯字典者行為完全不變。

變更：字庫會記錄到錄音資料中

即時錄音設定的術語庫與模糊詞校正，先前不會記錄到該場錄音的資料裡，事後無從查證當時用了什麼設定（音檔匯入一直都有記錄）。本版起兩者一致。

記錄的是你實際送出的設定內容，系統自動衍生的規則不列入。

客戶端建議

1. 確認字庫的語言鍵格式：使用完整代碼（zh-TW、en-US），不要用 zh、chinese 這類寫法。改版後格式不符的字庫會靜默失效。
2. 檢查字庫的語言歸屬：若你把英文術語放在中文的語言鍵底下、靠混合語音都能吃到，改版後在純英文的句子上不再生效。
3. 接收 config_updated 的新欄位：unknown_languages 與 inactive_languages 是目前唯一能提早發現設定問題的訊號。
4. 字幕跳動屬預期：中間結果不套校正、句尾才套。

V1.10.0

2026-08-21

新增：多聲道語者分離（實體聲道分離模式）

新增辨識模式 multi_channel：一場錄音接多支實體麥克風（最多 8 路），每路各自綁定一種轉錄語言，語者身分由聲道直接決定，不需依聲音特徵推斷，適合每位發言者配有專屬麥克風的場景。適用 transcribe 與 record；不適用於 conversation 與廣播，且不可與語音合成、多人語者分離併用。本功能需開通後才可使用，未開通時 start 回 invalid_recognition_mode。

• 實體聲道分離模式：start 帶 recognition_mode: "multi_channel"、channel_mode: "per_channel" 與 channels[]（每路含 channel_id、speaker_name、transcription_languages）；音訊格式僅支援 pcm，audio 每幀需帶 channel_id。
• 錄音中動態增減聲道：新增 action add_channel／remove_channel，錄音進行中即可加開或停用聲道；停用後該路已產生的逐字稿與音檔保留。
• 單路語言切換：新增 action set_channel_language，只更換單一聲道的轉錄語言，聲道編號與語者身分不變、逐字稿保持連續；多聲道下 switch_language 不適用，請改用本 action。
• 聲道狀態事件：新增 channel_status 事件，回報各聲道的狀態（preparing／ready／removed／error）與當下聲道數，供介接方呈現各路就緒狀況。
• 暫停補轉錄：暫停期間錄音檔照常保存、不出字；恢復後，暫停期間的談話會補進逐字稿（時間戳為實際講話時刻），補轉錄範圍以全場合計 60 秒的尾段為上限，超出部分僅保留於音檔。
• result 事件與逐字稿每句帶 channel_id，speaker_id 依聲道固定（格式 channel_{N}）。

新增錯誤碼：本版新增多聲道相關錯誤碼（channel_*／multichannel_* 系列），完整清單與說明見 錯誤碼參考。

計費：多聲道每分鐘依該分鐘內啟用的最高聲道數加收費用，第 1 路已含在基礎費率內，移除聲道後自次一分鐘起生效；詳見 計費說明。

完整規格見 WebSocket 語音翻譯。

客戶端建議

• 既有整合不受影響：未使用 multi_channel 的錄音行為與計費均不變。
• 多聲道需搭配指向性／近講麥克風並保持足夠間距；設備不符時的串音（一人講話多路收音）不在品質保證範圍，建議客戶端做選路（同一時刻只送能量最強的那一路）或確保物理隔離。

V1.9.2

2026-08-20

修正：多語轉錄時部分目標語言未被翻譯

多語轉錄（transcription_languages 設定多於一種語言）且翻譯目標語言與轉錄語言有重疊時，重疊的那個語言可能原樣回傳原文而未翻譯。

實際症狀（以轉錄與翻譯皆設定 zh-TW／en-US／ja-JP／ko-KR 為例）：

修正後，多語模式的來源語言改為逐句判定：只有該句實際語言與目標語言相同時才維持原文，其餘一律翻譯。單一轉錄語言與互譯模式不受影響。

已受影響的資料：修正只作用於新的錄音，已儲存的逐字稿不會自動補翻。若要補救，對受影響的錄音執行重新翻譯即可。重新翻譯依實際用量計費。

同時影響 origin.language：多語模式下該欄位改為回傳該句判定的語言，不再是整場固定值；無法明確判定時維持原設定值，欄位不會留空。若你的整合以此欄位判斷語言，請留意它在多語模式下會逐句變動。

修正：重新翻譯歷史逐字稿時未實際翻譯

對歷史錄音執行重新翻譯（GET /api/v1/sse/retranslate/{taskId}）時，部分句子會原樣回傳而未翻譯，常見於早期資料或當時語言判定有誤的句子。現已修正。

已受影響的資料：先前重新翻譯後仍是原文的句子，重跑即可正常翻譯，無須額外設定。重新翻譯依實際用量計費。

修正：部分用戶端錯誤被回成伺服器錯誤（500）

某些請求錯誤先前會回 500 internal_error，讓介接方誤判為伺服器故障而重試。現已回正確的狀態碼：

其餘 HTTP 層級錯誤一律保留原本的狀態碼；若該狀態碼沒有對應的專屬錯誤碼，錯誤碼為 http_error。

路徑不存在（404）、權限不足（403）、請求過於頻繁（429）、參數驗證失敗（422 validation_failed）、未通過認證（401）原本就正確，不受本次修正影響。

同時修正標頭遺失：節流回應（429）先前不帶 Retry-After 與 X-RateLimit-*，客戶端無從得知該等待多久，現已保留。

若你的整合把 500 當作「重試」的判斷依據，請改以實際狀態碼區分——4xx 代表請求本身需要修正，重試不會成功。

術語庫上限：文件更正，並為音檔匯入補上合計驗證

即時錄音的上限未變更，但先前文件的描述與實際行為不符，本次更正：

• 即時錄音 config 的 500 為所有語言合計的術語筆數，非每種語言各 500
• boost 僅在互譯模式佔用額外容量。單人、多語轉錄、多人語者分離、音檔匯入不受 boost 影響；互譯模式下一筆術語佔用 clamp(round(boost), 1, 5) 個名額（四捨五入，1.5 進位為 2），超出上限的部分不會生效

音檔匯入（行為變更）：術語庫的有效上限同為所有語言合計 500 筆。本次起，合計超過 500 筆會在上傳時直接回 422 並指出實際筆數；先前只逐語言驗證，合計超過時上傳會成功、但超出的術語不會生效也沒有提示。

若你的多語言字庫合計超過 500 筆，請先精簡再上傳——先前那些「上傳成功卻沒生效」的術語，本來就沒有作用。

文件補齊：翻譯字典的大小寫旗標

translation_dict 的 case_sensitive 欄位補進文件（欄位本身早已支援，本次僅補文件）：逐條選填，預設 false = 不分大小寫；設為 true 時僅在大小寫完全相符時套用。

同時新增大小寫旗標對照章節。fuzzy_correction 用 case_insensitive（預設 false = 嚴格），translation_dict 用 case_sensitive（預設 false = 寬鬆）——兩者欄位名互為反義、預設值代表的行為也相反。設錯不會有任何錯誤訊息，只會做出與預期相反的比對行為。

文件補齊：模糊詞校正的變體碰撞規則

同一個錯誤變體出現在多條規則時（碰撞以 incorrect 判定，不是 correct）：

• 大小寫旗標取嚴格優先——任一條沒開 case_insensitive，該變體即以嚴格比對處理
• 多條規則指向不同正確詞時，實際生效的那一條不保證順序，請勿依賴

因此把同一個 correct 拆成多條規則、各自設定大小寫是安全且支援的用法，只要各條的 incorrect 不重複。若同一個錯誤變體需要對到不同的正確詞，請自行擇一。

文件補齊：config 依序處理、失敗即中止

terminology、fuzzy_correction、translation_dict 依 terminology → fuzzy_correction → translation_dict 的順序處理。任一項驗證失敗會回錯並中止，該項與其後的區塊不會套用；排在它之前、已處理完成的區塊已經生效。

收到錯誤時不可假設設定完全未變更；修正後重送完整的 config 即可，三個區塊都是整批覆蓋，不會與先前的設定疊加。

V1.9.1

2026-08-13

新增：Ad-hoc 摘要端點（POST /api/v1/sse/summary）

新增對「請求自帶文字內容」生成摘要的 SSE 端點，不綁定任何錄音。適用於服務端沒有的內容——例如多段錄音合併後的完整逐字稿、使用者編輯後的逐字稿。生成結果僅串流回客戶端，不會儲存。

• 認證：僅接受 Header X-API-Key（不接受 query string 帶金鑰），認證失敗回真實 401/403。
• 計費：0.1 點／每 1,000 content 字元（與摘要相同費率），生成成功才計費。
• 重複請求保證：idempotency_key 必填、只在同一把 API Key 內有效；系統以整份請求內容（content＋所有摘要參數）判斷是否為重試。同一識別碼＋完全相同請求重試不重複計費（但會重新生成）；同一識別碼＋任一欄位不同回 409；失敗不佔用識別碼。
• 錯誤契約：串流開始前一律回真實 HTTP 狀態碼（401/403 / 422 / 404 / 400 / 402 / 409），與其他 SSE 端點的「200 + error 事件」慣例不同。

注意：早期版本曾有另一個同路徑端點（V1.8.0 移除）。本端點為全新契約——認證、計費與重複請求規則皆不同，請勿沿用舊整合程式。

新增錯誤碼（完整說明見 錯誤碼參考 – 摘要錯誤）：

完整規格見 Ad-hoc 摘要 SSE。

客戶端建議

• 需要以「多段合併後全文」或「編輯後全文」重生摘要者，改用本端點；切換模板、更換輸出語言的重生仍使用重新生成摘要。
• idempotency_key 建議使用你方系統的穩定識別碼（如合併批次 ID、版本 ID）；換一份新內容請帶新鍵。

V1.9.0

2026-07-31

新增：吃到飽方案

除點數制外，新增「吃到飽方案」：以合約授權固定的功能組合與使用上限，期間內使用方案內功能不逐分鐘扣點。方案的功能組合與各項上限（同時識別語言數、單次錄音上限、使用時數門檻、併發錄音上限）由後台依合約自訂。

• 方案不含的功能直接拒絕，不會回落為點數扣抵。
• 廣播一律不含在吃到飽方案內，廣播照點數計費。
• 基本功能（所有方案必含）：基礎語音轉錄、專業詞語庫、摘要、全文重翻。

詳見 計費說明 – 吃到飽方案。

新增錯誤碼（完整說明見 錯誤碼參考 – 方案限制錯誤）：

too_many_languages 語意擴充：details.max 除了系統上限（轉錄語言 10 種），也可能來自方案的「同時識別語言數上限」，details 帶 max 與 received。

新增：查詢我的方案端點

新增 GET /api/v1/me/plan（X-API-Key 認證，唯讀，零餘額也可查詢）：回傳目前計費制度（點數制／吃到飽）、方案功能組合、一次性功能、各項上限與目前用量、以及限制預計恢復時間。被 403／402 等方案限制擋下時，可用此端點查「我的方案含什麼、離上限多遠、限制何時恢復」。

詳見 我的方案 API。

變更：音檔匯入回應欄位

• POST /api/v1/imports/check-quota 回應新增 data.reason：null（通過）／insufficient_credit（點數不足，儲值可解）／plan_not_allowed（方案不含匯入，需升級方案）。
• POST /api/v1/imports 的 202 回應新增 data.downgraded_features（陣列）：方案含匯入但不含部分子功能（如語者分離、翻譯）時，該子功能會被略過、匯入照常進行，被略過的功能列於此欄位；空陣列＝無降級。

變更：remain_quota 語意（既有欄位）

對「被分配專屬額度」的 API Key，remain_quota 改為回傳該把 key 實際可動用的額度（專屬額度），而非帳戶總餘額；未分配專屬額度的帳號數值不變。影響 POST /api/v1/imports/check-quota 的 remain_quota，以及 WebSocket 錯誤訊息中的 remaining_budget。

客戶端建議

• 點數制的既有整合無需任何改動；本版新增錯誤碼僅在使用吃到飽方案時出現。
• 使用吃到飽方案的整合，建議在收到 plan_feature_not_allowed／plan_daily_limit_reached 時呼叫 GET /api/v1/me/plan，向使用者呈現方案內容與恢復時間，避免誤判為服務故障。
• 收到 concurrency_limit_reached 與 daily_limit_disconnect 時連線／帳號皆可繼續使用：前者待其他錄音結束後重試，後者可立即開始新的錄音。
• 若貴方會顯示 remain_quota，請留意其對「被分配專屬額度」的 API Key 已改為專屬額度語意。

V1.8.0

2026-07-29

調整：計費方式更新

本版調整多項服務的計費方式。

費率調整

互譯模式：語音合成改為分項計費

互譯整合費率（1.5 點／分鐘）原本已含語音合成；本版起語音合成改為分項計費，啟用時另計 1.0 點／分鐘。未啟用語音合成的互譯費率不變（仍為 1.5 點／分鐘）。錄音過程中可隨時開關語音合成，費率自該分鐘起隨之調整。

摘要與全文重新翻譯：改為依文字量計費

「字元」為逐字稿的實際字元數；不足一個計費單位仍以一個單位計，每次至少收 0.1 點。單句重新翻譯維持免費。

廣播：雲端翻譯費改為兩項相加

廣播的觀眾派送費原依「最大觀眾人數 × 翻譯語言帶」單一查表；本版改為「翻譯語言數」與「最大觀眾人數」各自查表後相加，並新增 10,000／20,000／30,000 人的費率級距（帳號預設上限仍為 5,000 人，需要更高上限請洽業務開通）。

同時，廣播不再另計「翻譯第 2 種語言起」的加乘 —— 多語言費用已完整包含在雲端翻譯費中。

移除：POST /api/v1/summary 端點

「對任意逐字稿生成摘要」的 REST 端點自本版起停止提供。

移除原因：該端點獨立於錄音流程之外，實際使用率為零；其認證方式亦與其他 REST 端點不一致（Authorization: Bearer vs X-API-Key），長期偏離主線維護。

替代方案：摘要功能維持兩條入口，皆與錄音綁定：

受影響對象：直接呼叫 POST /api/v1/summary 的整合。若貴方原本以此對「外部來源的逐字稿」生成摘要，請與服務窗口聯繫討論替代方式。

內容過濾降級的變更：原先文件建議在 SSE 重新生成摘要遇到 llm_content_filtered 時，改用本端點觸發自動降級。本端點移除後，請改為調整 prompt 或逐字稿內容後重試。

GET /api/v1/summary-templates（摘要模板查詢）為不同端點，不受影響。

客戶端建議

計費調整無需任何程式改動；若貴方有依費率試算成本的流程，請依新費率重新評估，完整費率表與計費範例見 計費說明。

若貴方整合有使用 POST /api/v1/summary，請依上方替代方案調整。

V1.7.7

2026-07-25

新增：部署版本查詢端點

新增 GET /api/v1/version（REST 服務）與 GET /version（即時服務），回報目前部署的版本與建置識別碼，供串接方在上線前做版本閘門檢查——例如「某項修正需 ≥ vX.Y.Z 才可上線」。

兩端點皆免認證：版本閘門若因認證問題失敗，會與「版本不符」混淆而失去把關意義。回應僅含版本與建置識別碼。

{ "service": "vas-api", "version": "1.7.7", "build": "a1b2c3d4e5f6" }

注意：即時服務與 REST 服務為獨立部署，版本可能不同步，請依要驗證的功能所屬範疇分別查詢。

版本閘門建議做法：本端點自 V1.7.7 起提供，因此「端點有回應」本身即代表版本 ≥ V1.7.7；若回 404 則表示版本早於 V1.7.7，需另洽服務窗口確認。

詳見 REST API · GET /api/v1/version。

客戶端建議

無需任何改動。若貴方的上線流程需確認 VAS 版本，建議改以此端點自動化，取代人工確認。

V1.7.6

2026-07-25

修正：廣播使用自訂摘要 prompt 時，錄音可能無法完成保存

主講端以自訂摘要模式（summary_mode: "custom"）開始廣播時，若該廣播另有設定通用摘要樣板，兩者會產生衝突，導致廣播結束後錄音無法完成保存。摘要本身仍會依自訂 prompt 正常生成，因此不易察覺。

本版修正後，自訂摘要模式將完整沿用主講端傳入的設定，不再套用廣播既有的通用樣板。使用通用樣板模式的廣播行為不變。

受影響對象：以 WebSocket start 帶 summary_mode: "custom" 開播、且該廣播設有 summary_template 的情況。若貴方廣播一律使用通用樣板，則不受影響。

文件更正：廣播設定分為「頻道預設值」與「當場設定」兩層

廣播是「頻道」概念，一個頻道可以多次開播，因此設定分為兩層：

PATCH 更新的是頻道預設值，因此 transcription_languages、translation_languages、speaker_diarization、tts_config、summary_template、summary_language 於下一次開播時才生效；這使得主辦方可在直播進行中，先為下一場預先調整設定。例外是 access_type、pass_code、max_viewers，因屬觀眾存取控制而會即時套用到進行中的直播。

此為行為說明的更正，API 行為未變更。先前文件一律描述為「即時調整設定」，未區分兩層，容易讓人誤以為更換摘要樣板會影響進行中的那一場；現已於功能說明與參數表逐欄標示。

修正：未指定摘要樣板的錄音，無法只調整摘要語言或輸出格式

conversation 與 broadcast 允許不指定 summary_template（摘要會沿用系統預設樣板）。此類錄音先前以 set_summary 只調整 summary_language 或 summary_plain_text 時，會被誤判為「缺少摘要來源」而回傳 summary_mode_field_mismatch。

本版修正後，只調整輸出語言或格式的請求不再檢查摘要來源。若要明確開啟自動摘要（auto_summary: true）或更換摘要來源，仍需提供樣板或自訂 prompt，規則不變。

客戶端建議

• 若貴方在直播進行中呼叫 PATCH 更換摘要樣板並依此顯示「已生效」，請調整為「將於下一場生效」，或改用 WebSocket set_summary 讓當場的收尾摘要即時採用新設定（V1.7.5 起支援，廣播亦適用）。
• 廣播若需使用自訂摘要 prompt，請於主講端 WebSocket start 帶入，並更新至本版以避免上述保存問題。

V1.7.5

2026-07-25

錄音進行中可更換摘要設定

新增 WebSocket action set_summary，可在錄音進行中更換停止時要套用的摘要設定，涵蓋通用樣板（builtin）與自訂 prompt（custom）兩種模式，也能改摘要語言、純文字輸出，或直接關閉本次的自動摘要。

即時錄音的摘要只在停止時生成一次，因此更換後「該次自動摘要」即採用最新設定；中途更換多次以停止前最後一次為準。先前開始錄音後就無法再更改，只能於停止後另外呼叫摘要重生成（等於多生成一份、多計一次費用），此限制自本版起解除。

• 摘要來源（模式／樣板／prompt）為整組替換，切換模式時會自動清除另一模式的欄位。
• 更換摘要來源不會自動開啟自動摘要；若錄音開始時已關閉，需另外帶 auto_summary: true。
• 斷線續接的 resume_ok 會回傳更新後的摘要設定，可直接用於狀態對齊。
• 詳見 set_summary。

摘要設定未指定通用樣板時的紀錄一致性

錄音若使用通用樣板模式但未指定樣板，系統原本就會採用預設的通用樣板生成摘要；自本版起，該預設樣板也會一併記錄於錄音資料中，使實際採用的樣板與紀錄一致。此為內部紀錄的補正，摘要內容與計費均不受影響。

客戶端建議

無需任何改動；set_summary 為新增能力，既有整合維持原行為。若您的產品允許使用者在錄音途中更換摘要樣板，建議改用本 action，可省下一次額外的摘要生成。

V1.7.4

2026-07-23

音檔匯入重試現在會保留自訂摘要與字庫設定

音檔匯入失敗後重試時，現在會保留原本的自訂摘要 prompt 與字庫設定（術語庫、模糊詞校正、翻譯字典），並在重試時一併重建；因此重試會正常重新生成摘要並套用字庫，逐字稿與摘要都會產出。

先前自訂摘要的匯入若失敗，重試不會重新生成摘要、需重新送出整包匯入 —— 此限制自本版起解除，直接重試即可。

翻譯字典現在也會影響摘要

當摘要以某個「目標語言」輸出、且該語言在翻譯字典中有對應條目時，摘要生成會盡量沿用字典指定的譯法，讓摘要用字與翻譯後的逐字稿一致。

• 適用範圍：即時錄音的收尾摘要，以及 SSE「重新生成摘要」（預覽與儲存）。
• 摘要以「來源語言」輸出時，翻譯字典（來源 → 目標）本就不適用。
• 屬盡力而為，非保證逐字取代；為行為擴充、既有整合無需改動。

音檔匯入的逐字稿補齊摘要追溯欄位

音檔匯入產生的逐字稿記錄現在也會帶摘要的追溯欄位（summary_mode、summary_template、summary_language、summary_plain_text、summary_prompt_snapshot），與即時錄音一致。屬附加欄位、向後相容，既有整合不受影響。

客戶端建議

無需任何改動。若先前因自訂摘要匯入失敗而改採「重新送出匯入」，現在可直接呼叫重試即可恢復摘要。

V1.7.3

2026-07-22

音檔匯入支援自訂摘要（custom）

音檔匯入的摘要現在支援 summary_mode=custom，與即時錄音、SSE 重生成一致：可送 summary_prompt（完整取代內建模板）＋ summary_prompt_slug（自訂識別碼）。

• 未指定 summary_mode：行為與先前完全相同（走 summary_template）。
• summary_mode=builtin：需帶 summary_template。
• summary_mode=custom：需帶 summary_prompt 與 summary_prompt_slug，且不可帶 summary_template（互斥）。

自訂 prompt 全文不落庫（與即時錄音一致）；因此失敗後 retry 的自訂匯入不會重新生成摘要（逐字稿仍正常產出，僅摘要留空）。（此限制已於 V1.7.4 解除，見上方；自 V1.7.4 起 retry 會保留自訂摘要並正常重新生成。）

音檔匯入的摘要模板修正

以往音檔匯入指定 summary_template 時，該模板實際上不會被套用 —— 不論指定 meeting、interview 或 course，產生的摘要都是同一種通用格式。

自本版起，匯入會正確套用所指定模板的內容，與即時錄音的行為一致。

注意：這代表既有整合的匯入摘要內容會改變（改為符合所指定的模板）。若你先前依賴匯入摘要的固定格式，請重新確認。未指定 summary_template 時行為不變。

模糊詞校正新增「忽略大小寫」選項

fuzzy_correction 的每一條規則新增選填欄位 case_insensitive。設為 true 時，該條規則的所有 incorrect 變體在比對時會忽略大小寫。

預設為 false，行為與先前完全相同 —— 既有整合不需要任何改動。

旗標是逐條設定的，同一個 correct 可以拆成多條規則分別設定：

{
  "zh-TW": [
    { "correct": "IPEVO", "incorrect": ["ltfo"], "case_insensitive": true },
    { "correct": "IPEVO", "incorrect": ["ivo"] }
  ]
}

上面的設定會把 LTFO、LtFo、ltfo 都校正成 IPEVO；但只有小寫的 ivo 會被校正，人名 Ivo 不受影響。

適用範圍：即時錄音的 config action 與音檔匯入。resume_ok 的設定快照也會回傳此欄位（值為 false 時省略）。

注意：開啟後誤傷面會擴大。若某個變體與一般詞彙或人名相同（例如 ivo 之於 Ivo），建議維持預設的嚴格比對。中文規則不受影響（中文沒有大小寫）。

客戶端建議：無需改動；需要時再逐條開啟。

V1.7.2

2026-07-22

互譯模式接受 speaker_diarization（行為變更）

以往互譯（type=conversation）只要帶 speaker_diarization=true 就會被拒絕。自本版起改為接受，但不會生效：互譯不進行語者分離。

其他錄音類型的行為不變。

計費：每分鐘費率跟沒有帶這個參數的互譯一樣，不會因此加收。不過這類請求先前會被拒絕、不會產生錄音也不計費，自本版起會正常建立錄音並開始計費。

客戶端建議：如果你先前為了避開這個錯誤，在互譯請求中拿掉了 speaker_diarization，維持現狀即可，不必改動。

互譯中途變更語言後，翻譯語言回報不再過時（修正）

以往互譯過程中變更語言後，resume_ok、Webhook 與錄音資料中的 translation_languages 會顯示變更前的語言。自本版起改為反映當前語言，浮動字幕的語言資訊也一樣。

即時翻譯本身一直是正確的，不受這個問題影響。

互譯的 translation_languages 是單一語言，代表當前的對方語言；如果中途變更過，最後留下的是最新一次的語言。

客戶端建議：如果你會用 resume_ok 或 Webhook 的 translation_languages 來判斷譯文語言，這個值自本版起才可信。

互譯的 speakers 語言代碼改為 start 階段就驗證（修正）

以往互譯用 speakers 指定語言時，如果語言代碼不在支援清單內，連線仍會正常開始、也能傳送音訊。但那場錄音不會建立，因此不會留下逐字稿，也不會產生任何用量紀錄。

自本版起改為在 start 階段直接回 400 invalid_transcription_language，details.field 是 speakers[].language，details.speaker_id 指出是哪一位 speaker。

客戶端建議：請確認 speakers 使用的是支援清單內的語言代碼。如果你的整合裡有拼錯的代碼，升版後會立即收到明確錯誤，而不是像先前那樣默默失效。

文件修正

• 更正多處「所有錄音類型都會即時翻譯」的敘述（record 自 v1.7.0 起不支援翻譯）
• 能力對照表更正：廣播支援語者分離（限單一轉錄語言）
• 互譯規則表補上：translation_languages 由伺服器指定、realtime_translation 固定為 true

V1.7.1

2026-07-22

多語轉錄不再加收費用（計費調整）

同時指定多種轉錄語言（自動語言偵測）自本版起不再加收費用 —— 來源語言數不影響每分鐘費率。原費率表中「多語轉錄（第 2 種語言起，每 +1）0.3 點／分鐘」一項已移除。

翻譯輸出語言的加乘維持不變（整句翻譯 +0.2、即時翻譯 +0.4，每多一種翻譯語言）。

受影響最明確的是互譯（conversation）：互譯依規格恆需 2 種轉錄語言，因此先前每分鐘固定被加收 0.3 點；本次調整後，互譯的實收金額回到費率表公告的整合費率。

客戶端建議：無需任何改動。使用多語言辨識的錄音（含所有互譯錄音）每分鐘費率會下降。詳見 計費說明。

V1.7.0

2026-07-22

record 錄音類型輕量化（破壞性變更）

record（純錄音）自本版起定位為輕量純語音辨識類型，行為調整如下：

• 翻譯不再支援：對 record 帶 translation_languages 會回 400 record_translation_not_allowed（start、switch_language、retranslate 三種即時路徑，以及事後逐字稿重翻／摘要翻譯端點皆一致）。
• TTS 不再支援：對 record 帶 tts_enabled=true 會回 400 record_tts_not_allowed。
• 摘要改為預設關閉、可選開啟：record 不再預設自動生成摘要；需帶 summary_template 或使用 summary_mode=custom 才生成。若帶 auto_summary=true 但未帶模板，回 400 record_summary_requires_template。
• 語者分離維持可用：record 仍可帶 speaker_diarization=true 進行多人語者分離。

計費上，純錄音的 record（未開啟摘要）僅計語音辨識用量，不含翻譯與 TTS 成本。

新增錯誤碼：record_translation_not_allowed、record_tts_not_allowed、record_summary_requires_template（見 錯誤碼 · 錄音類型限制錯誤）。

客戶端建議：

• 若你用 record 做純語音記錄（不需翻譯／摘要／TTS）：無需任何改動，且成本更低。
• 若過去對 record 帶了 translation_languages 或 tts_enabled=true：請移除這些欄位，或改用 transcribe 類型。
• 若過去依賴 record 預設自動產生的摘要：請改為明確帶 summary_template 或 summary_mode=custom，否則升版後將不再自動生成摘要。
• 既有 record 錄音資料不受影響（讀取、播放、既有逐字稿與摘要皆正常）；僅事後對其重新翻譯會被拒。

V1.6.10

2026-07-16

浮動字幕 feed 支援廣播主講者（直播中）

廣播主講者於直播進行中，可用與一般錄音相同的流程訂閱自己的即時逐字稿浮動字幕 feed：以 API Key 換取 owner feed_token（浮動字幕 Feed Token）→ 連線浮動字幕 SSE（浮動字幕 SSE）。

客戶端建議：廣播請監聽 broadcast_recording_ready 事件取得正式開播後定案的 task_id（standby 的 session_started 帶的是初始 ID、拿去換 token 會回 425），再據此換 feed_token。

端點、參數、回應格式皆不變；一般錄音的浮動字幕行為不受影響。

status 事件新增機器可讀 status 欄位

pause / resume / stop 的 status 事件（WebSocket 與浮動字幕 SSE）新增 status 欄位：live / paused / ended。詳見 WebSocket 事件 · status 與 浮動字幕 SSE · status。

客戶端建議：浮動字幕視窗（尤其主講者本人）請依 status 欄位動作——paused → 凍結、ended → 主動關閉視窗、live → 恢復。因浮動字幕 SSE 在錄音停止後不會自動關閉，未依 ended 關閉會凍結停留在最後一句。message 為顯示文字、不保證格式，請勿解析判斷狀態。此欄位僅出現於上述三種生命週期轉換；set_name 等其他 status 事件不帶。向後相容：既有欄位不變，未使用此欄位的整合不受影響。

浮動字幕 Feed Token：425 / 410 分流

換取浮動字幕 feed_token（擁有者與觀眾端）時，原本「錄音尚未就緒」與「錄音已結束」皆回 425，現分流為：

• 425 Too Early：錄音尚未就緒（建立中）→ 短延遲後重試。
• 410 Gone：錄音已結束 → 不再重試。

詳見 浮動字幕 Feed Token。客戶端建議：收到 410 應停止重試並關閉浮動字幕視窗。

語言切換事件回帶完整翻譯語言集

language_switch_start、language_switch_done、translation_language_removed 三個事件（WebSocket 與浮動字幕 SSE）新增 translation_languages 欄位：當前完整翻譯語言集的權威快照。詳見 WebSocket 事件。

背景：舊版事件只帶單一 translation_language，消費端無法分辨這是「新增語言」或「置換語言」，可能誤刪既有語言。

客戶端建議：收到上述事件時，直接以 translation_languages 覆寫本地翻譯語言集，不要再從單一 translation_language 推測操作語意。此舉一併解決 op:add／置換／亂序／重連遺漏等語言集同步問題。向後相容：純新增欄位，只認 translation_language 的既有整合不受影響。

浮動字幕重連一致性：語者事件納入補播、connected 反映當前語言集

浮動字幕 SSE（浮動字幕 SSE）兩項行為修正，解決「重連或中途加入的觀眾看到過時資訊」：

• 語者事件納入補播：speaker_renamed / speaker_reassigned / speakers_merged / speakers_auto_merged 現在會依原始時序重放（在其影響的句子之後）。客戶端建議：補播時比照即時處理——依 affected_sids 回溯更新既有句子的語者標籤；否則重連觀眾會看到改名前的舊語者名。
• connected 反映當前語言集：connected 事件的 translation_languages 現在為當前權威語言集（反映錄音中途的語言新增/移除），不再是開始錄音時的凍結值。

向後相容：無新欄位、無格式變更；僅補播內容更完整、快照更即時。

V1.6.9

2026-07-14

行為變更：翻譯輸出語言數上限提高至 12

translation_languages 數量上限由 8 種提高至 12 種（適用即時錄音、匯入、廣播；直連 API 生效）。屬放寬邊界，對既有 ≤8 語言整合完全相容。

• 輸入軸不變：轉錄（來源）語言上限仍為 10 種；輸入／輸出為兩個獨立維度。
• 廣播觀眾派送費新增「9–12 種語言」費率帶（見計費說明）。
• too_many_languages 錯誤同時涵蓋兩軸：轉錄 > 10 或翻譯 > 12 時觸發。

V1.6.8

2026-07-13

新增：廣播支援多語言轉錄輸入

建立／更新廣播時新增 transcription_languages（字串陣列，最多 10 個、不可重複），做為轉錄（來源）語言的主要欄位，可一次指定多個語言進行多語言連續辨識。

• 舊欄位 transcription_language（單一字串）標記為已棄用，但仍可繼續使用（向後相容，等同 transcription_languages 的第一個元素）。
• 建立／更新廣播的回應同時回傳兩個欄位：transcription_language（＝首元素，向後相容）與 transcription_languages（完整陣列）。
• summary_language 未指定時，預設改用第一個轉錄語言（transcription_languages 首元素）。

新增：觀眾資訊回傳來源語言陣列

廣播觀眾資訊（/info）在既有 source_lang（＝首元素）旁新增 source_langs（字串陣列），完整列出該廣播的所有轉錄語言。

行為變更：說話者辨識僅支援單一轉錄語言

啟用 speaker_diarization 的廣播僅支援單一轉錄語言。若同時提供多個轉錄語言，建立／更新請求會回 422（多語轉錄與說話者辨識互斥）。

客戶端建議

• 新的整合請改用 transcription_languages 指定轉錄語言；transcription_language 雖仍可用但已棄用，建議逐步汰換。
• 讀取廣播設定與觀眾資訊時，改以 transcription_languages / source_langs 為準，transcription_language / source_lang 僅保留首元素供相容。
• 需要說話者辨識的廣播請維持單一轉錄語言，避免觸發 422。

V1.6.7

2026-07-10

行為變更：即時錄音支援多語言即時翻譯

translation_languages 指定多個語言（最多 8 個）時，所有錄音類型（transcribe / record / conversation / broadcast）都會即時翻譯全部指定語言。此前非廣播類型僅實際翻譯第一個語言、其餘靜默忽略；本版起與文件既有承諾（多語言翻譯）對齊。

接收方式：每個語言各回一則獨立的 result 事件（同一 sid、translations 內單一語言 key），不會在一則事件中合併多語言。既有多語言客戶端注意：過去只收到第一個語言的譯文，升級後會開始收到全部語言——請以「sid + 語言代碼」累積譯文、不可互相覆蓋。

• interim（逐字）即時翻譯需 realtime_translation: true；預設 false 時整句完成才翻譯全部語言
• 部分語言翻譯失敗時其餘語言照常送達，失敗語言另收 error 事件（details.translation_language 指明語言）

行為變更：多語言場次的 switch_language 重新定義為新增／移除語言

翻譯語言為 2 個以上的場次，switch_language 必須帶 op 參數：

• op: "add"：新增單一語言並自動補譯既有句子（回應序列同單語言切換），上限 8 種
• op: "remove"：移除單一語言，回新事件 translation_language_removed；歷史譯文保留，至少需保留 1 種
• 多語言場次不帶 op 回新錯誤碼 switch_language_op_required（防止舊置換語意破壞語言集）

單語言場次維持既有置換＋批次重翻語意，客戶端無需調整。

新增錯誤碼：switch_language_op_required、switch_language_already_exists、switch_language_not_in_session、switch_language_last_language（詳見錯誤碼）。

計費說明

多語言翻譯的計費規則不變（一向按語言數量計費，自第 2 種語言起每分鐘加乘，詳見計費說明）；本版僅將實際翻譯交付補齊至與計費一致。點數消耗提醒：多語言即時翻譯的每分鐘點數消耗顯著高於單語言（8 種即翻約為單語言的 2.8 倍以上），點數不足時錄音會依既有規則中止，請留意餘額。

客戶端建議

• 多語言場次請以 translations 的語言代碼為 key 累積渲染，勿以最後一則覆蓋
• 需要逐字即時的多語言字幕請帶 realtime_translation: true
• 多語言場次調整語言改用 op: "add" / op: "remove"；偵測 switch_language_op_required 錯誤即代表後端已為 v1.6.7

參考文件

• WebSocket 參考 - start 多語言翻譯
• WebSocket 參考 - switch_language
• WebSocket 事件 - translation_language_removed
• 即時語音翻譯指南 - 多語言翻譯

V1.6.6

2026-07-09

新增：計費說明頁

新增計費說明頁，完整列出點數制費率：

• 點數定價：1 點 = TWD 1.5（≈ USD 0.047）。
• 基礎用量（即時錄音／匯入）：語音辨識、字庫修飾、多語轉錄、說話者辨識、翻譯（含每多一種翻譯語言的加乘）、語音合成的每分鐘費率。
• 互譯模式：即時互譯整合費率。
• 加值服務（一次性）：會議摘要、重新生成摘要、重新翻譯。
• 廣播計費：主講者端（內容處理）＋觀眾端（依最大觀眾人數 × 翻譯語言帶的觀眾派送費），含完整費率表與計費範例。

行為變更：逐字稿輸入語言數上限提高至 10

逐字稿的「輸入（來源／轉錄）語言」數量上限提高至 10 種，對齊語音辨識服務的多語言連續辨識上限。影響即時錄音（WebSocket）與音檔匯入。

• 說話者辨識模式仍僅支援單一來源語言（多語轉錄與說話者辨識互斥），此上限不適用於該模式。
• 翻譯（輸出）語言數上限不變（維持 8 種）。

文件明確化：廣播最大觀眾人數至少為 1

建立廣播時 max_viewers 最少為 1（API 原即驗證下限為 1，本版於文件與後台一併明確化）。

V1.6.5

2026-07-06

行為變更：五個語速等級的斷句靜音門檻全面調長

speaking_speed 五個等級對應的斷句靜音判斷門檻已調整。門檻拉長代表更能容忍句中停頓、減少整句被誤切，代價是各等級的斷句時機相應延後。

• 預設值仍為 normal，但對應門檻由 500ms 調整為 800ms。
• 等級名稱、API 介面與 set_speaking_speed 用法皆不變；升級後無需修改整合程式。

客戶端建議

• 升級後可預期斷句時機較先前略慢、句子更完整；若原本依賴 very_fast 取得最即時的斷句，最快門檻由 150ms 變為 300ms（very_fast 仍是最快選項）。

V1.6.4

2026-07-04

新增：resume_ok 回傳本次錄音設定（state reconcile）

• resume_ok 新增 settings 物件，回傳 session 目前持有的本次錄音設定（語速、音訊格式、語言、TTS、術語庫/模糊詞/翻譯字典、摘要設定、錄音名稱、互譯對話模式與 speaker 語言映射等），供前端斷線續接／整頁重新整理後以伺服器權威值對帳、覆寫本地快取。
• 回傳的是當前值（含錄音中經 set_speaking_speed / config / set_name / set_tts / switch_conversation_mode / set_speaker_language 變更後的結果），並以 API 格式呈現（如 speaking_speed 回 "normal" 等級字串）。
• 欄位明細見 連線與認證 — settings 物件。

續接格式約束（重要）

• settings.audio_format 回傳 start 當時的音訊格式；續接連線必須沿用同一格式（伺服器以原格式解碼、不重新協商）。

行為變更

• conversation_language_change_failed 錯誤回應的 details 不再附內部錯誤細節（與 set_speaking_speed_failed 一致；請以錯誤碼判斷、顯示通用失敗文案）。

文件修正

• set_speaking_speed 支援範圍說明修正：非多人（multi_speaker）辨識模式皆支援（含廣播、多語 LID），非僅單人／互譯。

客戶端建議

• 收到 resume_ok 後，以 settings 為權威來源對帳本地設定快取（特別是 refresh／多分頁情境）。
• 舊客戶端可忽略 settings 欄位，不影響既有行為。

V1.6.3

2026-07-03

語音辨識斷句設定調整

新增：錄音中動態調整語速

• 新增 set_speaking_speed action，可於錄音進行中調整語速（斷句節奏）。套用時辨識會短暫中斷。成功回應 speaking_speed_changed（帶回已套用的語速）。僅單人 / 互譯模式支援，多人（multi_speaker）模式不套用。

行為變更：移除 segmentation_mode

• start options 的 segmentation_mode（斷句策略 auto / by_time）選項已移除，不再提供。斷句節奏改由 speaking_speed 統一控制。若仍傳送此欄位，伺服器會忽略，不影響其他參數。

speaking_speed 說明更新

• 預設值 normal 對應 500ms 靜音判斷門檻（所有環境皆相同）。
• 五個等級：very_slow（1000ms）/ slow（700ms）/ normal（500ms）/ fast（300ms）/ very_fast（150ms）。

客戶端建議

• 需要錄音中調整斷句節奏者，改用 set_speaking_speed（建議在 UI 控制項放開後才送，避免短時間內連續切換）。
• 若原本有傳送 segmentation_mode，可移除該欄位（伺服器已忽略）。

參考文件

• WebSocket API — set_speaking_speed

V1.6.2

2026-07-02

set_name（設定錄音名稱）行為修正與辨識強化

行為變更

• 錄音名稱超過長度上限時，現在會明確回傳 set_name_too_long 錯誤，回應的 details 帶 max_length（先前此情況不會回傳任何訊息，客戶端會等到逾時）。
• 錄音名稱長度上限為 60 字。

成功回應辨識（新增 event 欄位）

• set_name 成功回應新增 event: "name_set" 與 name 欄位，供客戶端精準辨識。
• 為相容既有整合，成功回應的 action 維持 "status" 不變。

Deprecated 預告

• 以 action: "status" 判斷 set_name 成功的舊方式已 deprecated（不建議），未來版本可能移除該相容行為。建議改用 event: "name_set"（搭配 name 欄位）辨識。

錯誤碼

• set_name 的錯誤碼為 set_name_empty 與 set_name_too_long。

客戶端建議

• 直連 WebSocket 協定、且以 action: "status" 辨識 set_name 成功的客戶，請改用 event: "name_set"；其餘客戶無需變更。

參考文件

• WebSocket API — set_name

V1.6.1

2026-06-29

新增：浮動字幕觀眾分享

浮動字幕除錄音擁有者本人外，新增「觀眾分享」：擁有者可開啟分享、取得分享密鑰（放入分享連結／QR Code），讓現場其他觀眾以唯讀方式共同觀看，免登入、免 API Key、不另計費。

新增端點

新增事件

• 浮動字幕 SSE 新增 viewers 事件，回報目前觀看人數與上限（count / max）。
• 浮動字幕 SSE 新增 subtitle_closed 事件：主講者「關閉分享」或「停止錄音」時，伺服器主動送出並結束觀眾連線；觀眾端收到後應停止重連。主講者本人連線不受影響。

行為說明

• 同一場錄音的觀眾人數有上限（以伺服器設定為準，預設 10 人，不含擁有者本人）；請以 viewers 事件的 max 欄位為準，勿寫死數值。觀眾人數已達上限時，連線回 429。
• 主講者「關閉分享」會即時結束所有觀眾連線（送 subtitle_closed），分享連結同時失效、無法重連；「停止錄音」亦同。觀眾為被動接收方。

客戶端建議

• 既有浮動字幕（擁有者本人）整合不受影響、無需調整。
• 如需提供觀眾共看：於擁有者端呼叫 subtitle-share 取得分享密鑰、組成分享連結；觀眾端以公開端點換取 Token 後連線浮動字幕 SSE。
• 觀眾端務必處理 subtitle_closed 事件：收到後關閉連線並停止自動重連，避免無效重連。

參考文件

• Subtitle Feed Token API
• 浮動字幕 SSE

V1.6.0

2026-06-27

Breaking Change：移除 recording_id 舊命名（命名統一完成）

自 V1.4.1 起公告的 recording_id → task_id 命名統一，本版完成最後一步：全面移除 recording_id 舊欄位與舊路徑，所有任務識別碼統一為 task_id。

task_id 的值與舊 recording_id 完全相同（同一筆錄音的 UUID）。本次遷移只是改欄位名／路徑，識別碼本身不變。

受影響範圍（需調整）

1. WebSocket payload：session_started 與 resume_ok 事件不再帶 recording_id 欄位，請改讀 task_id。
   • 此項原預告於 V2.0.0 移除，本版提前至 V1.6.0 一併完成。
2. REST 端點移除：下列 recordings 舊路徑已移除，請改用對應的 tasks 路徑（行為完全相同、識別碼同值）：

   已移除（舊）	請改用（新）
   PATCH /api/v1/recordings/{recordingId}/speakers/rename	PATCH /api/v1/tasks/{taskId}/speakers/rename
   PATCH /api/v1/recordings/{recordingId}/speakers/reassign	PATCH /api/v1/tasks/{taskId}/speakers/reassign
   PATCH /api/v1/recordings/{recordingId}/entries/{sid}	PATCH /api/v1/tasks/{taskId}/entries/{sid}

3. SSE 連線訊息文字：歷史紀錄／重新翻譯／摘要重生成串流的 connected 訊息標籤由 (recordingId: ...) 改為 (taskId: ...)（純文字提示，識別碼值不變）。

不受影響（無需調整）

• current_recording_id：廣播查詢回應中的 current_recording_id 欄位保留不變（指「當前進行中錄音的 UUID」，語意明確、非本次清理對象）。
• SSE 重翻路徑：GET /api/v1/sse/recordings/{taskId}/entries/{sid}/retranslate 保留不變（路徑中的 recordings 為既有命名，參數已是 taskId）。
• 任務查詢、音檔／逐字稿匯出、Webhook（data.task_id）等既有以 task_id 為主的介面完全不變。

客戶端建議

• 將所有讀取 recording_id 的程式改讀 task_id（值相同，可直接替換）。
• 將所有 /api/v1/recordings/{id}/... 的 REST 呼叫改為 /api/v1/tasks/{id}/...。
• 若曾以字串比對 SSE connected 訊息中的 recordingId:，請改比對 taskId:（更建議改以事件型別判斷，勿依賴訊息文字）。

參考文件

• WebSocket - 回應事件
• REST - Speakers
• REST - Entries

V1.5.12

2026-06-26

錄音 options 子欄位文件化（speaking_speed / segmentation_mode / profanity_handling）

WebSocket start 的 options 子欄位正式文件化，可微調 STT 斷句與敏感詞處理：

• speaking_speed：very_slow / slow / normal（預設）/ fast / very_fast——調整斷句的靜音判斷門檻；講者較慢時調慢，可避免句中停頓被誤切。
• segmentation_mode：auto（預設）/ by_time——斷句策略；by_time 搭配 speaking_speed 調整門檻。
• profanity_handling：mask（預設）/ remove / show——敏感詞處理。

客戶端建議

• 全為選用；不帶時維持預設（normal / auto / mask），既有整合無需任何調整。
• 慢速講者或希望整句不被切斷時，可試 speaking_speed: slow。
• 多人模式（multi_speaker）目前不套用 speaking_speed / segmentation_mode。

參考文件

• WebSocket - Voice Translation（start → options 子欄位）

V1.5.11

2026-06-25

新增功能：浮動字幕逐字稿 feed

新增「浮動字幕」唯讀逐字稿串流：可用獨立連線即時訂閱進行中錄音的逐字稿（來源語言原文＋目標語言翻譯），適合桌面浮動字幕視窗、第二螢幕字幕等情境，與錄音本身的連線分離、可在不同裝置/視窗單獨開啟。

• 換取 token：POST /api/v1/auth/tasks/{taskId}/subtitle-feed-token（以 API Key 換取綁定該錄音的短效 feed_token，僅錄音擁有者可換取）。
• 訂閱串流：GET /tasks/{task_id}/subtitle?feed_token=...&lang=...（SSE）。收 connected / result（原文與翻譯）/ status / 語者與互譯語言切換等事件；原文以 sid+is_final 就地替換，翻譯以 sid 對應原文行繼承說話者。
• 支援 lang 篩選目標語言、連線補播與自動重連。連線時序邊界：未開始 425、已結束 410、token 失效 401、連線過多 429。

客戶端建議

• 浮動字幕視窗建議在錄音開始後再換取 feed_token；剛開錄時若回 425（錄音尚未就緒）請短延遲後重試。
• feed_token 有效期 15 分鐘、連線期間自動延長；長時間錄音請在到期前重新換取。

參考文件

• 浮動字幕 SSE
• Subtitle Feed Token API

V1.5.10

2026-06-20

新增功能：API Key 來源 IP 規則（白名單 + 拒絕清單）

可為每一把 API Key 設定來源 IP 規則（於用戶後台設定），同時套用於 REST API 與即時 WebSocket：

• 白名單（allow）：只允許清單內 IP 使用該金鑰。
• 拒絕清單（deny）：命中即拒絕該來源，適合擋掉特定惡意/攻擊 IP、其餘照常放行。

判定順序（deny 優先）：命中任一拒絕規則即拒；有白名單則須命中其一；兩者皆空＝不限制（向後相容）。兩者並存時，最終可通過＝在白名單內 ＆ 不在拒絕清單（同一 IP 同時在兩邊會被拒絕）。金鑰外洩也無法從未授權（或被拒絕）的 IP 使用。

新增錯誤碼

• auth_ip_not_allowed（403）：來源 IP 不被允許（不在白名單、或命中拒絕清單）。請從已授權的 IP 位址存取。
• auth_account_blocked（403）：帳戶已被封鎖。請聯繫技術支援。

行為變更

• 帳戶被封鎖時，API Key 驗證改回 403 auth_account_blocked（與一般「API Key 無效」的 401 區分）；即時 WebSocket 握手亦會以此原因拒絕。

客戶端建議

• 若您為金鑰設定了 IP 規則，請確保所有呼叫端（含 WebSocket）皆從已授權的 IP 位址發出；拒絕清單優先於白名單。
• 請將 auth_ip_not_allowed、auth_account_blocked 納入 403 錯誤處理；兩者皆為 fatal，重試無益，須改正來源 IP 或聯繫技術支援。

參考文件

• 錯誤碼

V1.5.9

2026-06-10

強化：斷線續接新增時間基準欄位

為斷線續接補上三個時間基準欄位，協助客戶端對齊伺服器時鐘與逐字稿時間軸。

新增

• session_started 事件新增 server_time（伺服器當下 unix 毫秒，作為時鐘基準參考；前端可用它與收到當下的 client 時間估算時鐘偏差）。
• resume_ok 事件新增 server_last_offset_ms（斷點對應的逐字稿時間軸位置，毫秒，基於已處理音訊長度）。
• resume_ok 事件新增 server_recording_ms（續接後逐字稿時間軸實際接續的錄音頭時間，毫秒，含靜音；供前端把錄音秒數標頭對齊到逐字稿所用的同一條時間軸）。

提醒

• 兩種時間不可混用：寬限期（resume_grace_seconds）以 wall-clock 真實時間計、斷線期間持續倒數；server_last_offset_ms 基於音檔時間軸、斷線期間凍結。判斷「能否重連」一律以 wall-clock 為準。

參考文件

• 連線與認證 - 斷線續接

V1.5.8

2026-06-08

新增功能：WebSocket 斷線續接（Session Resume）

WebSocket 連線意外中斷時，客戶端可在**寬限期（預設 45 秒）**內帶 resume_token 重連，接回原本的錄音會話——沿用同一 recording_id 與句子編號（sid），逐字稿時間軸從斷點接續，無需重新開始整場錄音。

新增

• session_started 事件新增 resume_token、resume_grace_seconds 兩個欄位（請保存）。
• 新增 resume_ok 事件（續接成功，含 server_last_sid）。
• 新增 4 個續接錯誤碼：resume_token_invalid、resume_grace_expired、resume_ownership_mismatch、resume_unavailable（皆 error 嚴重度，非 fatal）。
• 連線文件新增重連實作範例（JavaScript）。

客戶端建議

• 收到 session_started 時保存 resume_token。
• 偵測到連線中斷後，於寬限期內：重取一張新 Ticket → 以 Sec-WebSocket-Protocol: ["ticket.<新>", "resume.<token>"] 重連。
• 收到 resume_ok 後，像 start 之後一樣重開音訊流（WebM 須送新容器）。
• 收到任一 resume_* 錯誤 → 重取 Ticket 後送全新 start。

不變項

• 不使用斷線續接的既有客戶端無需任何變更；斷線行為與過去一致（一律全新 start）。
• 斷線那幾秒的音訊不會補回、不計費（時間軸無縫接續）。
• api_key 即信任邊界：採「最後連線者勝」策略，請勿跨信任域共用同一把 api_key。

參考文件

• 連線與認證 - 斷線續接
• 錯誤碼

V1.5.7

2026-05-20

文件更新（無 API 行為變更）

對外 API 行為完全不變，本版為文件補充與用詞調整版。

新增使用指南：摘要 Prompt 客製化

新增 摘要 Prompt 客製化指南，把原先散落在 6 份 reference 文件中的摘要客製化規格集中為單一 guide：

• builtin / custom 兩種摘要模式的互斥規則與適用場景
• REST POST /api/v1/summary、WebSocket start action、SSE regenerate/summary 三條入口的對應欄位
• 逐字稿記錄欄位（含 summary_prompt_snapshot 審計欄位、summary_fallback_level / summary_dropped_segments 兩個 fallback 審計欄位）
• 敏感詞與不雅字眼處理章節，整合三條路徑（客戶 prompt → 中性模式、逐字稿 → STT profanity_handling 遮罩、逐字稿 → 摘要層段落省略）並明示「API 層不會主動拒絕含敏感詞的請求」
• 內建安全防護機制（內容中性化指引、prompt injection 防護）與字元長度限制
• Node.js / Python / WebSocket 三組完整範例

文件首頁的「功能指南」表格新增此 guide 入口。

文件用詞調整

對外文件的用詞全面調整為更通用的描述（summary_fallback_level 等欄位值不變，僅文字描述調整）。

參考文件

• guides/summary-customization.md（新增）
• 文件首頁

V1.5.6

2026-05-19

文件對齊修正版（無 API 行為變更）

本版為文件校對版，對外 API 行為完全不變。下列項目若你曾依舊文件實作，請依當前規格調整。

Token 格式

• broadcast_token：4 字元短碼（字符集 a-z0-9）
• viewer_access_token：64 字元 alphanumeric 字串（非 JWT，無 payload 結構，請勿嘗試解析）

HTTP 狀態碼

• sse_missing_target_lang / sse_unsupported_language：422
• broadcast_token_invalid（viewer verify 端點）：401

錯誤碼字串

• POST /api/v1/imports 配額不足：stt_quota_exceeded
• 廣播觀眾 SSE 找不到廣播：broadcast_session_not_found
• 廣播觀眾 SSE 容量已滿：broadcast_capacity_exceeded
• sse_translation_failed error 事件的 context 為 sse

WebSocket 事件命名

• retranslate 成功事件：action: "translation"
• 音檔上傳失敗：以 type: "error" envelope 送出（error_code 為 storage_upload_failed / storage_connection_failed / storage_queue_full），無獨立 upload_error action

新列入文件的錯誤碼

參考文件

• reference/rest/viewer.md
• reference/websocket/events.md
• reference/websocket/voice-translation.md
• reference/sse/retranslate.md

V1.5.5

2026-05-13

Breaking Change：摘要 API 改為 mode-aware

V1.5.4 推出的「template + custom_prompt 共用」設計改為互斥：客戶必須在每次摘要請求中選擇 mode=builtin（套用內建模板）或 mode=custom（客戶 prompt 完整取代內建模板）。

客戶端必須遷移：v1.5.4 客戶端不修改欄位將收到 422。

REST POST /api/v1/summary、SSE regenerate/summary、WebSocket start 三條入口統一新欄位

舊（v1.5.4）→ 新（v1.5.5）對照：

互斥規則：

• mode=builtin：template 必填、prompt / prompt_slug 禁帶
• mode=custom：prompt / prompt_slug 必填、template 禁帶
• 違反 → 422 summary_mode_field_mismatch

GET /api/v1/tasks/ 回應欄位

data.tasks[] 中：

• 新增 summary_mode（builtin / custom / null）
• summary_template 改為 effective slug（custom mode 下回傳客戶 slug，等同送出時的 prompt_slug）
• 移除 summary_custom_prompt_slug（合併至 summary_template）

舊資料相容：未生成摘要的錄音 summary_mode 為 null；既有 builtin 模式錄音的 summary_template 保留原值。

逐字稿記錄結構異動

新增 top-level 欄位（不是 nested 在 summary 物件下）：

GET /api/v1/sse/history/transcribe/{taskId} 的 init_summary 事件除既有 text 外，新增 mode / template / plain_text / prompt_snapshot（custom mode 才有值）讓客戶端追溯，以及 fallback_level / dropped_segments（fallback 觸發時才有值）。

WebSocket 新增 outbound event

• summary_done：摘要生成完成（含 summary_mode / summary_template (effective) / summary_plain_text / tokens_used / summary_fallback_level / summary_dropped_segments，不含 final_content）
• summary_error：摘要生成失敗（含 error_code / message）

客戶端不再需要輪詢逐字稿記錄判斷摘要是否完成。

內容過濾自動降級

Custom mode 的客戶 prompt 或逐字稿內容若被內容過濾擋下，系統會自動依下列順序降級而非直接回失敗：

觸發降級時，單次摘要會產生多次生成請求，最壞情況最多計費 7 次生成請求的用量，且每次請求的用量都會計入帳單。

客戶端對應實作：依 summary_fallback_level 顯示 UI 提示（見上表），summary_dropped_segments 可用於告知用戶實際省略了哪些區段。

規格範圍：本版的自動降級對 WebSocket realtime 摘要（錄音結束自動生成）與 檔案匯入摘要 兩條路徑生效。SSE regenerate/summary 端點將於後續版本支援，當前版本被擋下時仍回 llm_content_filtered。

Custom mode 的內容中性化指引

Custom mode 的摘要會自動套用一條內容中性化指引：「對於原文中可能出現的口語化、情緒性或敏感詞彙，以中性、客觀的語言概括其意旨，避免逐字引用或重複」。此指引不開放客戶端設定。

此指引本身不會被保存。客戶 prompt 原文仍透過 summary_prompt_snapshot 欄位儲存作為審計依據，與 summary_fallback_level 互補：

• summary_prompt_snapshot = 客戶意圖（原 prompt 內容）
• summary_fallback_level = 實際執行路徑（標準模式 / 中性模式 / 段落省略模式）

Custom mode 的 prompt 安全性

請勿把不可信的終端用戶輸入直接拼進 prompt。

新增錯誤碼

客戶端建議

1. 新增 mode 必填欄位 — 既有呼叫 templateSlug=meeting 的請求改為 mode=builtin&template=meeting
2. 欄位重新命名 — customPrompt → prompt、customPromptSlug → promptSlug；且這兩欄只在 mode=custom 下使用
3. 移除 persistCustomPrompt — custom mode 自動保留 prompt 內容
4. templateSlug 改為 template — 並且僅限 mode=builtin 使用
5. 逐字稿記錄改為 top-level 欄位 — 不再嵌套在 summary 物件下
6. 客戶端可從 done event / summary_done event 判斷是否已儲存 — 看 persisted: true/false，不需要再依 HTTP method 推斷

參考文件

• reference/rest/summary.md
• reference/sse/regenerate-summary.md
• reference/rest/summary-templates.md
• reference/websocket/voice-translation.md
• reference/websocket/events.md

V1.5.4

2026-05-12

新增功能：摘要 Prompt 客戶客製化

企業客戶現在可以在不改動 IPEVO 內建模板的前提下，為摘要 API 加入自家規則。本版新增三個正交的客戶端參數，並把摘要重生成端點拆成「預覽」與「存檔」兩個動詞，避免 HTTP GET 帶副作用的設計斷層。

完全向後相容 — 不傳新欄位 = 行為與舊版一致。

POST /api/v1/summary 新增欄位

SSE start / done event 也增補對應欄位（custom_prompt_slug、plain_text、final_content、custom_prompt_snapshot），詳見 reference/rest/summary.md。

/api/v1/sse/regenerate/summary/{taskId} 拆兩個端點

客戶端建議：若你的整合方原本依賴「打 GET 後後端記錄自動更新」，請改打 POST。GET 改為純預覽，不再寫入任何後端狀態。

done event 新增 persisted: bool 欄位，客戶端可直接從 payload 判斷此次是否已儲存，不需要再依靠 HTTP method 推斷。

WebSocket start action 新增 4 欄位

summary_custom_prompt / summary_custom_prompt_slug / summary_plain_text / summary_persist_custom_prompt，與 REST 端點欄位一一對應，限制相同。

新增端點：GET /api/v1/summary-templates/{slug}

提供內建模板的完整原始文字（system_prompt / template_prompt / output_format），供企業客戶整合時參考既有基礎，再決定 custom_prompt 該補什麼。

GET /api/v1/summary-templates 同時新增 ?category=summary|medical|legal|all 篩選與回應 data[].category 欄位（預設 summary，向後相容）。

新增錯誤碼

行為變更

• summary_text_empty / summary_text_too_long HTTP 狀態碼修正：原本回 500，本版修正為符合語意的 400。
• POST /api/v1/summary 錯誤事件 details 不再包含 LLM 原始錯誤訊息：回給客戶端的 details 只保留 provider 標示。
• GET preview 仍會計費：產生預覽與存檔耗用相同資源。重複呼叫 GET 會重複計費，但不會變更任何已儲存的內容。

路徑與欄位命名規範

• customPromptSlug 是客戶自訂 pass-through 識別碼（與既有 templateSlug exists 校驗的語意不同）。命名上前者為「客戶端追溯用」，後者為「VAS 內建模板查表用」。
• summary_custom_prompt_slug 會隨每份摘要一併保存（上限 64 字元），方便事後查詢「這份摘要對應哪個客戶模板」。
• custom_prompt_snapshot（opt-in）只在客戶設定 persist_custom_prompt=true 時才隨逐字稿記錄保存。

安全控管

• 所有端點需 API Key 認證
• 系統不會保存 custom_prompt 或逐字稿全文於診斷紀錄中（僅保存長度與 slug）
• LLM 錯誤訊息會被 sanitize（不曝露 raw error 給客戶端）
• custom_prompt 跨租戶完全隔離（Session-scope，無記憶持久化）

Bug 修正與內部改善

• WebSocket start action 的 recording_id 欄位 deprecation 預告版號統一為 V2.0.0（events.md 原寫 V1.6.0，與程式碼註解不一致）
• SSE sse-api.md 修正失效的 TOC anchor（指向 audio 段落但本文已遷移至獨立 reference/sse/audio.md）
• 改善文字清理：中日韓文字與 Emoji 不再被誤切或誤拒
• 摘要重生成的 fullText 加入 100,000 字元上限

參考文件

• reference/rest/summary.md（新增）
• reference/rest/summary-templates.md（補 ?category= 與 GET /{slug}）
• reference/sse/regenerate-summary.md（重寫為 GET / POST 二端點規格）
• reference/websocket/voice-translation.md（補 summary_custom_prompt* 4 欄位 + 3 錯誤碼）

V1.5.3

2026-05-07

Breaking Change：speaker_id 命名翻轉

V1.3.12 為了支援語者編輯，新增 original_speaker_id 欄位來保留原始 ID，但留下「同一名稱在不同階段語意不同」的設計斷層：WebSocket 即時錄音的 speaker_id 是原始 ID（如 Guest-1），SSE 歷史音檔載入後 speaker_id 變成顯示名（如 王經理，已套 alias）。前端常因此拿錯欄位丟進 PATCH /speakers/reassign。

本版做一次性翻轉，不向下相容：

翻轉後，speaker_id 在所有介面（WebSocket / SSE / REST）一致指向原始 ID；新增 speaker_label 表示套 alias 後的顯示標籤。語者編輯（rename / reassign / merge）一律以 speaker_id 為定位 key。

REST API 欄位變更

PATCH /api/v1/tasks/{taskId}/speakers/rename

speaker_id 仍可同時接受顯示標籤做連續改名（如先把 Guest-1 改名為「王經理」，再用「王經理」改為「王總」）；解析後的 response speaker_id 永遠是原始 ID。

PATCH /api/v1/tasks/{taskId}/speakers/reassign

target_speaker_id 必須是原始 ID（取自 init_sentence.speaker_id）；reassign 不接受顯示標籤。

PATCH /api/v1/tasks/{taskId}/speakers/merge

WebSocket 事件變更

SSE 事件變更

init_metadata.speaker_aliases（「原始 ID → 顯示標籤」映射）行為與欄位不變。

客戶端建議

• 使用 WebSocket 即時錄音的客戶：升版前同步 result.origin.speaker_id 與新增 result.origin.speaker_label 的處理；rename body 改送 { "speaker_id": "...", "new_label": "..." }
• 使用 SSE 歷史音檔的客戶：init_sentence.speaker_id 現在是原始 ID（過去是顯示名），改用 speaker_label 顯示
• 做語者編輯（rename / reassign / merge）的客戶：
  • rename → 用 speaker_id（原始 ID 或當前顯示標籤皆可）+ new_label
  • reassign → target_speaker_id 必須是原始 ID（取自 init_sentence.speaker_id，不能送顯示標籤）
  • merge → source_speaker_id / target_speaker_id 仍可送原始 ID 或當前顯示標籤
• 做 TXT/SRT/CSV 匯出整合的客戶：new_label 新增控制字元/換行驗證；若先前送過含換行的標籤會收到 422，請改為單行內容
• 不做語者編輯、僅消費 transcript 文字的客戶：影響極小，唯一行為差異是若有舊代碼把 speaker_id 當顯示名直接渲染，需改用 speaker_label

資料相容性

• 不做向下相容：舊逐字稿資料（V1.3.12 ~ V1.5.1，含 speaker + original_speaker_id）需經資料轉換才能在新版讀取
• 新錄音不受影響：V1.5.3 以後新建的 transcript blob 直接使用新欄位

文件更新

• reference/rest/speakers.md：rename / reassign / merge 三端點 body / response 全面對齊
• rest-api.md L2280–2455：speakers 摘要對齊新欄位
• reference/websocket/voice-translation.md L975–1127：rename_speaker / reassign_speaker / merge_speakers 三 action
• reference/websocket/events.md L405–495：speaker_renamed / reassigned / merged 三 event
• websocket-api.md L1310–2552：rename / reassign / merge 兩段（前段 actions + 後段 events）對齊
• reference/sse/history.md L135–195：init_sentence schema + 客戶端建議
• reference/sse/broadcast-viewer.md L300–365、L605–630：viewer 廣播事件 + JS 範例
• sse-api.md L240–475、L750–795：broadcast origin/translation + history init_sentence schema
• guides/speaker-management.md L140–390：範例 + JS handler
• examples/curl.md、examples/python.md、examples/javascript.md：所有 rename / reassign / merge 範例 + TS interface

參考文件

• REST - Speakers API
• WebSocket - Voice Translation
• WebSocket - Events
• SSE - 歷史音檔串流
• 指南 - 說話者管理

V1.5.1

2026-05-07

Bug 修正：POST /api/v1/imports 補上術語 / 校正欄位的長度驗證

文件多處承諾的長度限制（如 term 最大 100 字元）過去在檔案匯入路徑沒有真正生效，超長內容會被悄悄接受。本版補回，行為與文件承諾對齊。

行為變更（與文件承諾對齊）

POST /api/v1/imports 對下列欄位新增 422 拒絕條件（先前會被接受）：

限制值與 WebSocket config action 一致；先前只有 WebSocket 路徑會擋，本版把檔案匯入路徑補齊。

客戶端建議

若先前曾透過 POST /api/v1/imports 送過超長 term（>100 字元），現在會收到 422。前端應在送出前自行檢查長度並提示使用者。WebSocket 路徑無變化。

V1.5.0

2026-05-07

無對外變更

本版無對外 API 變更，客戶無需任何動作。

舊命名（recording_id）將於 V1.6.0 全面移除，客戶端遷移指引請見 V1.4.1 客戶端建議。

V1.4.3

2026-05-07

無對外變更

本版無對外 API 變更，客戶無需任何動作。

V1.4.2

2026-05-07

無對外變更

本版無對外 API 變更，客戶無需任何動作。

V1.4.1

2026-05-06

命名統一：以 task_id 為跨介面任務識別碼

過去同一筆任務在不同介面有不同欄位名（WebSocket 用 recording_id、Webhook 用 task_id、部分 REST path 變數混用 {recordingId} / {taskId}），整合方需自行對齊三邊命名。本版啟動命名統一週期，新整合請統一使用 task_id。

WebSocket 變更（向後相容）

• session_started 事件 payload 同時帶 task_id 與 recording_id，兩者值完全相同（同一筆錄音的 UUID）
• recording_id 欄位標記為 Deprecated，仍正常送出；預計 V1.6.0 移除
• 文件補強：session_id 為 WS 連線層級識別碼（連線結束即失效），與 task_id（任務識別碼）為不同層級

REST API 變更（向後相容）

新增 /api/v1/tasks/{taskId}/... alias 路徑，與既有 /api/v1/recordings/{recordingId}/... 行為完全相同：

客戶端建議

• 新整合：統一使用 task_id 欄位與 /api/v1/tasks/{taskId}/... 路徑，避免後續再次遷移
• 既有整合：無需立即修改。recording_id 與 /api/v1/recordings/... 在 V1.x 期間持續可用，建議在排程內遷移，最遲於 V1.6.0 釋出前完成
• ID 對齊邏輯：若同時依賴 WS 與 Webhook，可直接以 WS 的 task_id（或舊名 recording_id）對齊 Webhook data.task_id，三者為同一 UUID
• session_id 不要用於對齊：session_id 僅在 WS 連線生命週期內有意義，不會出現在 Webhook 與 REST

移除時程預告（V1.6.0）

V1.6.0 將移除 WS payload 中的 recording_id 欄位，並移除 /api/v1/recordings/{recordingId}/... 路徑。詳細時程將於 V1.6.0 釋出前另行公布。

不變項

• Webhook payload：data.task_id 既有命名不變
• 既有 /api/v1/tasks/{taskId}/... 端點：保持不變

V1.4.0

2026-05-06

新功能：歷史錄音原文編輯 + 自動重翻

使用者可修正 STT 辨識錯誤後重新生成翻譯，工作流見 Entries API 典型工作流。

• 新端點 PATCH /api/v1/recordings/{recordingId}/entries/{sid}：編輯單句原文；首次編輯時會把原始辨識結果保留在 original_text_raw，並記錄 original_text_edited_at；該句已生成的語音會重新產生
• 新端點 GET /api/v1/sse/recordings/{taskId}/entries/{sid}/retranslate：重新翻譯單一句子（可指定語言或重翻所有已存在語言），支援樂觀鎖（expectedRevision）
• 編輯與重翻分離：PATCH 只改原文不動翻譯，前端可決定何時觸發重翻

歷史紀錄 SSE 暴露編輯標記

historyTranscribe init_sentence 事件在被編輯句子上會帶 original_text_raw（STT 原始）與 original_text_edited_at，前端可顯示「已編輯」標記與「還原原文」功能。

安全性修補

• retranslate / retranslateSummary 加入使用者過濾：兩個既有 SSE 端點先前存在水平權限漏洞（IDOR），允許讀取他人錄音。本版補上權限檢查，他人錄音回 recording_not_found。
• 重翻 / 重生摘要要求錄音已完成：retranslate / retranslateSummary / retranslateEntry / regenerateSummary 四個端點要求 processing_status === completed；未完成時回 recording_not_completed。

新增錯誤碼

詳見 error-codes.md。

客戶端建議

• 編輯 STT 原文後：建議呼叫 PATCH 後立即觸發單句重翻 SSE，並帶上 PATCH 回應的 revision 作 expectedRevision，避免併發覆寫
• 顯示編輯標記：以 init_sentence 事件內 original_text_raw 欄位存在性（'original_text_raw' in data）判斷是否被編輯過，不要用文字比對（使用者可能編輯後又改回原值）
• 錄音狀態：對未完成的錄音呼叫重翻 / 編輯 / 重生摘要會回 recording_not_completed，前端應在 UI 阻擋這些操作直到 processing_status === completed

V1.3.13

2026-05-06

行為變更（Breaking Changes）

• WebSocket audio_format 鎖定為 pcm 與 webm：原本接受 5 種格式（pcm / webm / mp3 / wav / m4a）收斂為僅接受 pcm 與 webm，與文件 reference/websocket/voice-translation.md 既有規格一致。客戶若送 mp3 / wav / m4a 將收到 audio_format_unsupported（過去會被悄悄解碼成功，屬未文件化的隱性行為）。檔案匯入仍走 POST /api/v1/imports，不受影響。

文件更新

• 音檔下載 Content-Type 一律 audio/mp4：rest-api / SSE audio / tasks export / history playback / curl / javascript 多處文件統一為「所有錄音音檔一律以 M4A 容器（AAC 編碼）回傳」，移除原本「動態決定」的循環敘述。
• 檔案匯入支援格式收斂為 mp3 / wav / m4a：移除文件中對 mp4 與 webm 的提及，以對齊實際接受的格式（guides/file-import.md、reference/rest/imports.md）。

客戶端建議

• 使用 WebSocket start action 的客戶：請務必明確指定 audio_format 為 pcm 或 webm；若先前曾依賴未文件化的 mp3 / wav / m4a 隱性支援（極少數情境），請改走 檔案匯入 API。
• 下載錄音音檔的客戶：所有新錄音 Content-Type 固定為 audio/mp4、副檔名 .m4a。若儲存中仍存有舊錄音，下載仍可能收到 audio/webm，建議保留對舊副檔名的處理分支以涵蓋歷史資料。

參考文件

• WebSocket - Voice Translation
• REST - 任務音檔匯出
• SSE - 歷史音檔串流
• 指南 - 檔案匯入
• 指南 - 歷史播放

V1.3.12

2026-05-04

注意，已於 V1.5.3 翻轉：本版引入的 original_speaker_id 欄位與「speaker_id 為顯示名」的設計已被 V1.5.3 的命名翻轉取代。本段保留作為歷史紀錄；新整合請直接參考 V1.5.3 規範，不需再實作此版的客戶端建議。

新增功能

• History SSE 補欄位以對齊 Transcribe 語者編輯 UX：歷史紀錄的 init_metadata 與 init_sentence 事件各補一個欄位，讓前端能完整重用即時錄音頁的說話者編輯選單（單句重新指派 + 全域重命名）。
  • init_metadata 新增 speaker_aliases（object）：「原始說話者 ID → 顯示名」映射。無別名時為 {}（空物件，非空陣列）。供前端在送 PATCH /speakers/rename 前做撞名預檢，可涵蓋「在後端存在但因被 rename 過而畫面上沒出現的原始 ID」這類隱性衝突。
  • init_sentence 新增 original_speaker_id（string|null）：未經 alias 替換的原始說話者識別碼，提供給 PATCH /speakers/reassign 作為 target_speaker_id 來源。
  • 舊資料 fallback：舊錄音若沒有 original_speaker_id，會自動退回 speaker_id，不會讓編輯入口失效。

行為變更

• 無 breaking change。兩個欄位皆為純新增，忽略未知欄位的既有整合不受影響，無須版本協商。

文件更新

• sse-api.md L156-198：init_metadata / init_sentence 範例與欄位表加入新欄位說明
• reference/sse/history.md L103-180：同步補齊 reference 細節版的 schema

客戶端建議

• History 詳情頁要做語者編輯的客戶：請從 init_sentence.original_speaker_id 取得 reassign 用的原始 ID（不要用 speaker_id，那是已套 alias 的顯示名）；用 init_metadata.speaker_aliases 做 rename 前的撞名預檢。
• 不做語者編輯的客戶：可忽略新欄位，現有解析行為不受影響。

參考文件

• SSE API - 歷史紀錄事件
• Reference - 歷史紀錄 SSE
• Recording Speaker API
• 說話者管理指南

V1.3.11

2026-05-04

行為變更（Breaking Changes）

• STT 拒絕 bare en 代碼（V1.3.10 changelog 原宣稱已移除但實際未生效）：客戶若送 en 將收到 422 invalid_transcription_language，請改用 en-US / en-GB 等完整 BCP 47 代碼。
• TTS 移除 4 個從未可用的 locale：it-CH、ar-IL、ar-PS、en-GH。這 4 個 locale 的 TTS 從未真正可用，過去請求其 voice 會失敗。STT 仍支援這 4 個 locale。

新增功能

• TTS 擴充至 154 種語言、325 個 voice
  • 中國方言（4 個新增）：zh-CN-henan、zh-CN-guangxi、zh-CN-liaoning、zh-CN-shaanxi
  • 南亞語系（5 個新增）：bn-BD 孟加拉語（孟加拉）、ta-LK 坦米爾語（斯里蘭卡）、ta-MY 坦米爾語（馬來西亞）、ta-SG 坦米爾語（新加坡）、ur-PK 烏爾都語（巴基斯坦）
  • 東南亞語系（1 個新增）：su-ID 巽他語（印尼）
  • 東歐語系（1 個新增）：sr-Latn-RS 塞爾維亞語（拉丁字母）
  • 北美原住民語系（2 個新增）：iu-Cans-CA 因紐特語（加拿大音節）、iu-Latn-CA 因紐特語（加拿大拉丁字母）

文件更新

• languages.md TTS 區段重寫，明確標示：
  • 145 個 STT locale 中有 141 個 STT/TTS 雙端皆支援；4 個（it-CH、ar-IL、ar-PS、en-GH）僅 STT 支援
  • 154 個 TTS locale 中有 13 個僅 TTS 支援（4 個 zh-CN 方言 + 9 個其他語言）
• guides/tts.md 數字更新（142→154 種語言、304→325 個 voice）
• 文件首頁 TTS 描述更新

支援數量

客戶端建議

• 使用 en 簡碼的客戶：請改為 en-US 或其他完整 BCP 47 代碼。
• 使用 it-CH/ar-IL/ar-PS/en-GH 做 TTS 的客戶：原本就會在語音服務端失敗，請改用同語系的其他 locale（例：it-CH → it-IT、ar-IL → ar-SA、en-GH → en-NG）。STT 不受影響。
• 想用新增的 13 個 TTS-only locale 的客戶：可直接呼叫 GET /api/v1/tts/voices?language=zh-CN-henan 等取得 voice 列表。

參考文件

• 語言清單 languages.md
• TTS 指南 guides/tts.md

V1.3.10

2026-04-30

文件更新

• languages.md 數字修正
  • 語音辨識語言總數 119 種 → 145 種
  • 語音翻譯支援 117 種 → 143 種（145 扣除 jv-ID 爪哇語、wuu-CN 吳語）

本版有遺留問題，請見 V1.3.11：本版原宣稱「已移除 en、語言數完全一致為 145」，但實際並未移除 "en"（仍為 146），亦未處理 TTS 端的 it-CH/ar-IL/ar-PS/en-GH（TTS 從未可用）與 13 個 TTS-only locale 的缺漏。完整對齊修正於 V1.3.11 完成。

客戶端建議

• 本版僅文件層數字修正，不影響運行中的整合。

參考文件

• 語言清單 languages.md

V1.3.9

2026-04-29

新增功能

• Webhook Secret Bootstrap 流程：解決客戶端首次整合 webhook 時無法取得 secret 的矛盾。Dashboard 新增「產生 Webhook Secret」按鈕，讓使用者先取得 secret 設定到接收端，再回頭設定 webhook URL。設定 URL 時的 probe 將以雙方一致的 secret 簽名，可一次通過。
  • 新增端點：POST /dashboard/api-keys/{id}/webhook/regenerate-secret（Dashboard 限定，與 webhook 設定共用速率限制，每位使用者每分鐘 10 次）
  • 行為：產生 64 字元隨機 secret 並保存，不送 probe、不動 webhook URL；明文僅在產生當下於 Dashboard 顯示一次
  • 重生影響：執行後舊 secret 立即失效，既有接收端會收到簽章不符的 webhook 直到接收端切換新 secret

行為變更

• 清除 Webhook URL 不再清除 Secret：PATCH /dashboard/api-keys/{id}/webhook 在 webhook_url 設為 null 時，webhook_secret 將保留不動。Secret 與 URL 改為各自獨立 lifecycle。客戶可先產 secret、稍後再設 URL，中途送空 URL 不會弄丟 secret。
• Dashboard 不再以明文回傳 webhook_secret：GET /dashboard/api-keys/{id} 回傳改為 webhook_secret_masked（前綴遮罩 + 後 4 碼）與 has_webhook_secret 布林。明文僅在剛產生時顯示一次。

文件更新

• guides/webhook.md：「方式二：API Key 級 webhook_url」改寫為兩步流程（產生 secret → 設定 URL），新增 Webhook Secret 生命週期章節，安全驗證章節加 Bootstrap callout。

客戶端建議

• 首次整合：在 Dashboard 點「產生 Webhook Secret」、複製到接收端 .env、啟用 HMAC 驗證並重啟服務後，再回 Dashboard 填入 webhook URL。
• 既有客戶：完全相容，無需任何改動。既有 webhook_url 與 webhook_secret 行為不變。
• Secret rotation：建議在接收端短暫接受新舊兩把 secret，dashboard 重生後 in-flight webhook 處理完畢再下架舊 secret。

V1.3.8

2026-04-27

新增功能

• 翻譯服務不可用偵測（session-level）：新增錯誤碼 translation_service_unavailable。當 LLM 翻譯服務連續失敗達閾值，後端會發出一次 session-level 錯誤事件，讓前端能顯示全域「翻譯暫不可用」提示，避免使用者只看到滿頁失敗的個別句子灰字。
  • 觸發條件：
    • llm_timeout / llm_provider_error / llm_rate_limit / llm_request_failed 連續失敗 5 次升級
    • llm_auth_failed / llm_deployment_not_found / llm_quota_exceeded 1 次就立即升級（設定/帳務問題）
    • llm_content_filtered 不計入（內容問題，非服務問題）
  • 去重：每個 session 只通知一次；任一句翻譯成功則重置計數，可再次觸發
  • payload：type: "error"，severity: "error"（不是 fatal — 不應斷線），不帶 sid，details 含 provider、last_error_code、fail_count
  • 觀眾通知：廣播模式下，所有觀眾（不限語言）也會收到此事件（透過 SSE event: error 通道）

文件更新（規範同步）

延續 V1.3.7+ 前端反應的規範盲點，本次完成：

• error-codes.md — 句子級錯誤判斷規則：在「嚴重程度說明」表下方新增 sid 規則段落，明示**「當錯誤帶 sid 時，無論 severity 為何都應視為 sentence-level 錯誤，不應斷線」**。fatal + sid 的組合僅代表該句嚴重失敗，session 整體仍可繼續。
• error-codes.md — translation_service_unavailable 錯誤碼註冊：在「翻譯服務錯誤」段落新增此錯誤碼及完整觸發規則說明
• websocket-api.md：「錯誤訊息格式」段落新增 session-level translation 錯誤範例（不帶 sid，severity error）
• sse-api.md — retranslate 段補 per-sid error 規則：明確列出「失敗句改發 event: error 帶 sid + error_code，與 translation 交錯出現」的規範與 payload 格式（V1.3.7 已實作但只在 reference 子目錄記載）
• reference/sse/broadcast-viewer.md：補 translation_service_unavailable 範例與特有錯誤碼條目
• reference/websocket/events.md：清掉 translation_error dead spec（程式碼從未發出此 action 事件，實際走的是 type: "error" 通道）

客戶端建議

• 既有的句子級錯誤處理（type: "error" 帶 sid）無需任何改動。
• 若想顯示「翻譯服務不可用」全域提示，新增監聽：當收到 error_code === "translation_service_unavailable"（不帶 sid）時顯示 banner / toast；待後續任一句翻譯成功（再收到 translation 事件）即可解除。
• 切勿把 translation_service_unavailable 視為斷線訊號 — STT（原文）仍會持續運作。

參考文件：

• 錯誤碼參考
• WebSocket API – 錯誤訊息格式
• SSE API – retranslate 事件格式
• reference/sse/retranslate.md
• reference/sse/broadcast-viewer.md – 特有錯誤碼

V1.3.7

2026-04-24

行為變更

• 即時錄音：靜音任務統一走正常完成流程：即時錄音（WebSocket）過程全程靜音、雜訊或無法辨識出任何句子時，現在仍會產生空逐字稿（entries: []），並以 task_complete 事件結束。此行為與 V1.3.5 的檔案匯入流程對齊，realtime 與 import 兩條來源現在共用「零辨識結果視為合法 completed」語意。
• SSE 歷史紀錄：不再回 sse_transcript_not_found 於靜音情境：GET /api/v1/sse/history/transcribe/{taskId} 對靜音任務不再回傳 sse_transcript_not_found 錯誤，而是發送完整事件序列（init_metadata → init_summary(text='') → init_done(totalSentences=0)）。客戶端應以 totalSentences === 0 判斷並顯示「無語音內容」空狀態。

Bug 修正

• 修正 History 頁面靜音錄音卡在「處理中」：先前全程靜音的即時錄音，載入歷史紀錄時會收到 sse_transcript_not_found（語意上為「尚未處理完成」），使 UI 永久停在 loading。修正後靜音錄音一律會產生逐字稿（entries 為空陣列），與音檔匯入一致。

客戶端建議

• 若先前對 sse_transcript_not_found 有「待重試 / 輪詢中」的處理邏輯，可保留作為防禦性 fallback（例如 blob 上傳延遲），但不應再用於判斷「任務無語音」——應改以 init_done.totalSentences === 0 判斷。
• 建議 UI 在 totalSentences === 0 時提示可能原因（音量過小、全程靜音、辨識語言與音檔不符），與 V1.3.5 匯入場景的提示文案一致。

文件更新

• 歷史紀錄 SSE 新增「邊界情境：無語音內容」章節，並訂正 sse_transcript_not_found 的處理建議描述

參考文件：

• 歷史紀錄 SSE
• 匯入進度 SSE
• 音檔匯入指南 – 音檔無法辨識時的行為

V1.3.6

2026-04-23

新增功能

• Tasks API：新增 POST /api/v1/tasks/{taskId}/force-fail：將卡在非終態（recording / importing / uploading / pending / processing）的任務強制標記為失敗
  • Body 可選 reason（最長 500 字元）
  • 觸發 recording.failed webhook，payload.failure_source 為 user_forced
  • 已是終態的任務會得到 invalid_processing_status（422）
• Tasks API：新增 POST /api/v1/tasks/{taskId}/retry：將 failed 狀態的任務重新送出處理
  • 前置條件：processing_status = failed 且 audio_status = success 且 transcript_status = success
  • 不符前置條件回 invalid_processing_status（422），details 欄位會帶 audio_status / transcript_status 幫助定位

行為變更

• 內部 API PATCH /api/v1/internal/recordings/{id}/status 加入終態保護：對已處於 completed / failed 的錄音若嘗試寫入不同狀態會回 409 Conflict（payload 帶 current_status 與 attempted_status）。幂等放行：推相同終態視為 no-op 回 200。此變更配合 force-fail 端點，避免即時錄音服務仍在運行時把使用者手動操作的結果覆蓋回去。
• 錯誤碼 invalid_processing_status（422）擴充適用範圍：新增為 force-fail 與 retry 的通用回應；details 會帶 current_status，retry 場景額外帶 audio_status 與 transcript_status

文件更新

• Tasks API 新增 force-fail 與 retry 兩支端點說明
• 錯誤碼對照表 新增 invalid_processing_status 條目與「處理狀態不符」子章節

參考文件：

• Tasks API
• 錯誤碼對照表

V1.3.5

2026-04-22

行為優化

• 音檔匯入：空白辨識結果過濾：當音檔因整段靜音、音量過小、雜訊或辨識語言與音檔不符而導致語音辨識結果為空時，後端現會統一過濾空白 phrase，不再產生大量 00:00 / 空文字的佔位片段
• 零辨識結果為合法 completed 狀態：此情境下匯入任務仍以 status: completed 結束（不是 failed），task_id 正常產出，但後續載入的逐字稿 entries 為空陣列、segments_count 為 0
• 預算依實際時長扣除：無法辨識的音檔仍依音檔時長扣除月度預算（不退還）

客戶端建議

• 載入逐字稿（SSE /api/v1/sse/history/transcribe/{taskId}）後，若累計句子數為 0，顯示「此音檔未辨識出語音內容」空狀態
• 不應將零辨識結果視為錯誤分支，應走完成分支後以句子數判斷
• 建議 UI 同時提示可能原因（音量過小、全程靜音、辨識語言與音檔不符）

文件更新

• 音檔匯入指南 新增「音檔無法辨識時的行為」章節
• Imports API 在 status 狀態流轉下補充 completed 邊界情境說明
• 匯入進度 SSE 在 completed 事件下補充零辨識結果的行為註記

參考文件：

• 音檔匯入指南
• Imports API
• 匯入進度 SSE

V1.3.4

2026-04-22

新增功能

• Tasks API：新增 GET /api/v1/tasks/{taskId}/transcript/export：下載任務逐字稿，支援 五種格式 — txt、srt、sbv、vtt、csv
  • 輸出內容包含原文與所有翻譯語言
  • CSV 以 UTF-8 BOM 開頭、欄位 index,start,end,speaker,text,<每翻譯語言一欄>、時間 HH:MM:SS（無毫秒）
  • SRT 時間 HH:MM:SS,mmm；SBV 時間 H:MM:SS.mmm，原文與翻譯以 | 串為單行；VTT 使用 WEBVTT 表頭
  • 檔名採用 {錄音名稱}-transcript.{ext}（RFC 5987 UTF-8 編碼）
  • 新增錯誤碼 recording_transcript_not_ready（422）

行為變更（Breaking）

• 語者分離與多語言互斥改為硬性拒絕：recognition_mode: multi_speaker 搭配多個 transcription_languages 時，原本會發出警告並自動截斷到第一個語言，現改為直接回傳 diarization_multilang_conflict 錯誤並拒絕開始
  • 錯誤 severity 從 warning 調整為 error
  • 前端需在使用者送出 start 前即限制「語者分離」與「多語言」二擇一，或處理此錯誤並引導使用者調整設定
  • 影響端點：WebSocket voice-translation / start

文件更新

• Tasks API 新增 transcript/export 完整規格與五種格式輸出範例
• 錯誤碼參考 新增 recording_transcript_not_ready
• curl、Python、JavaScript 範例新增「任務匯出」章節
• 文件首頁 API 參考表 Tasks 端點計數從 8 更新為 9

參考文件：

• Tasks API - transcript/export
• 錯誤碼參考
• WebSocket API 參考
• 說話者辨識指南
• 語音互譯指南

V1.3.3

2026-04-21

新增文件

• Tasks API：補上 GET /api/v1/tasks/{taskId}/audio/export 端點的完整文件（原先實作存在但文件遺漏），包含參數、動態 Content-Type、錯誤碼及前端下載範例
• 說明該端點與 SSE /api/v1/sse/audio/{taskId} 的差異：前者用於離線下載（Content-Disposition: attachment），後者用於播放（支援 Range Request）

文件修正

• 修正 Voice Translation Actions 互譯模式 speakers 欄位說明表格：欄位名從 speaker 更正為 id，與 JSON 範例及實際服務行為一致
• 修正文件首頁 API 參考表端點計數：Tasks 從 7 改為 8（新增 audio/export）、Broadcasts 從 9 改為 6（原本計數錯誤）

參考文件：

• Tasks API
• Voice Translation Actions

V1.3.2

2026-04-07

文件結構調整

• 移除 3 個已棄用的舊版文件（error-codes.md V0.6、languages.md V0.1、authentication.md V0.1）
• 將 appendix/error-codes.md 和 appendix/languages.md 移至根目錄，取代棄用版本
• 更新所有交叉引用連結

V1.3.1

2026-03-26

批次任務管理

• 新增 PUT /api/v1/tasks/batch/pin：批次更新釘選狀態，單次最多 100 筆
• 新增 DELETE /api/v1/tasks/batch：批次刪除任務，單次最多 100 筆
• 兩個端點皆僅影響屬於當前用戶的任務，回應包含 affected_count

批次廣播撤銷

• 新增 DELETE /api/v1/broadcasts/batch：批次撤銷 PENDING 狀態的廣播，單次最多 100 筆
• 非 PENDING 狀態的 ID 會被忽略，回應包含 affected_count

參考文件：

• Tasks API
• Broadcasts API

版本：V1.24.1 最後更新：2026-10-07