リアルタイムテキスト読み上げ v2 | Fish Audio API ドキュメント

公開 Realtime TTS WebSocket v2 プロトコルで音声をストリーミングします。

Realtime TTS v2 は既存クライアントとの互換性のために維持されています。新規統合では上位の v3 ページを使用してください。

エンドポイントとプロトコル

ブランド	エンドポイント
Fish Audio	`wss://realtime.fishaudio.org/v2/tts/live`

サブプロトコル realtime.tts.msgpack.v2 を指定してください。アプリケーションメッセージは JSON テキストではなく MessagePack バイナリフレームです。既存の /v1/tts/live 統合は互換性のため継続しますが、新規統合は上位の v3 契約を使用してください。このページは v2 クライアントの保守専用です。

認証

Authorization: Bearer API_KEY
Sec-WebSocket-Protocol: realtime.tts.msgpack.v2

ブラウザに長期 API キーを渡さないでください。信頼できるバックエンドが POST /v2/tts/browser-tickets で、短時間・一回限り・Origin バインド済みのチケットに交換します。ブラウザは最初の MessagePack フレームとして { event: 'auth', token: 'rtv2_ticket_...' } を送信します。認証情報を 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: 'ja',
    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` は正の連番で、1 フレーム最大 2,000 文字です。
`flush`	reliable	`event`、`event_id`、`segment_id`	なし	空でないバッファを確定し、1～128 文字の一意な `segment_id` を使います。
`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 です。