即時文字轉語音 v2
透過公開的 Realtime TTS WebSocket v2 協定串流產生語音。
Realtime TTS v2 僅為現有客戶端保留；新接入請使用上級 v3 頁面。
端點與子協定
| 品牌 | 端點 |
|---|---|
| Fish Audio | wss://realtime.fishaudio.org/v2/tts/live |
連線必須宣告 realtime.tts.msgpack.v2 子協定。所有應用層訊息都是 MessagePack 二進位幀，不是 JSON 文字。現有 /v1/tts/live 接入仍保留相容服務；新接入應使用上級 v3 協定，本頁僅供維護 v2 客戶端。
驗證
Authorization: Bearer API_KEY
Sec-WebSocket-Protocol: realtime.tts.msgpack.v2不要把長期 API 金鑰交給瀏覽器。可信服務端應透過 POST /v2/tts/browser-tickets 換取短期、單次使用且綁定 Origin 的票據。瀏覽器把 { event: 'auth', token: 'rtv2_ticket_...' } 編碼成第一個 MessagePack 幀。不要把憑證放進 URL。
流程與輸入
connect → authenticated → start → ready → input → audio → finish預設 simple 模式不要求 request_id 或事件 ID；收到 ready 後傳送 { event: 'input', text }：
{
event: 'start',
request: {
voice_id: 'PUBLIC_VOICE_UUID',
model: 'fishaudio-s21pro-flash',
format: 'mp3',
speed: 1,
volume: 0,
language: 'zh',
chunk_length: 200,
latency: 'normal'
}
}只有需要明確分段、冪等與斷線恢復時才設定 start.mode='reliable'。reliable 模式要求 event_id、request_id、text.sequence 與 flush.segment_id。
客戶端事件包括 auth、start、input、text、flush、stop、ping。simple 模式通常只使用 start 和 input。
客戶端事件入參
每個事件都是 MessagePack Map，未知欄位會被拒絕。reliable 模式的 event_id 要求從 start 開始，先前的 auth 可以省略。
| 事件 | 模式 | 必填欄位 | 選填欄位與預設值 | 約束與行為 |
|---|---|---|---|---|
auth | 選擇模式前 | event、token | event_id | 僅供未帶 Authorization 標頭的瀏覽器票據驗證使用。 |
start | simple、reliable | event、request | mode: "simple"、event_id、request_id、retry_failed | reliable 必須提供 event_id、request_id；重試也僅限 reliable。 |
input | simple | event、text | event_id、commit: true | 文字不得為空；整個緩衝請求最多 10,000 字元。 |
text | reliable | event、event_id、sequence、text | 無 | sequence 是連續正整數；每個訊框最多 2,000 字元。 |
flush | reliable | event、event_id、segment_id | 無 | 提交非空緩衝區；segment_id 是 1–128 字元的唯一識別碼。 |
stop | reliable | event、event_id | 無 | 在所有已接受分段完成後結束請求。 |
ping | simple、reliable | event；reliable 還需 event_id | simple 可帶 event_id，另可帶 timestamp | 服務端回傳 pong。 |
PCM 回應包含 sample_rate、channels、bit_depth。
目前格式為 mp3, wav, opus。當供應商和模型支援時，speed 為 0.5 到 2、volume 為 0 到 10、chunk_length 為 50 到 1000。不支援的參數會回傳 unsupported_parameter。
省略 parameter_profile 時維持舊 v2 行為：volume 為 0 到 10，未知或不支援的欄位會被拒絕。使用 parameter_profile: "product_v1" 時，volume 為 -20 到 20，並可使用 stability、similarity、pitch、text_normalization、language、latency、emotion、instructions、optimize_instructions、chunk_length。服務端會限制支援參數的範圍、忽略模型不支援的控制項，並在 ready.effective_request 回傳最終生效值。
公開 voice_id 必須與模型相容。目前供應商為 FishAudio，模型為 fishaudio-s21pro-flash。連線前請透過 GET /v2/tts/capabilities 查詢 Fish Audio 支援的格式與參數。
服務端事件包括 authenticated、ready、input_ack、segment_accepted、audio、usage、segment_completed、request_status、warning、error、finish、pong。simple 客戶端只需處理 ready、audio、error、finish；reliable 模式需等待 input_ack 與 segment_completed。audio.audio 是 MessagePack 內的原始位元組。PCM 事件會包含 sample_rate、channels、bit_depth。
穩定錯誤碼包括 authentication_failed、authentication_required、already_authenticated、permission_denied、invalid_message、invalid_messagepack、invalid_state、idempotency_conflict、empty_segment、segment_too_large、session_limit_exceeded、quota_exceeded、client_backpressure、unsupported_parameter、voice_not_found、model_not_found、provider_unavailable、provider_timeout、generation_failed、billing_failed、connection_closed、internal_error。