TTS エンドポイントの比較

Cartesia は、テキストを音声に変換する 3 つの方法を提供します。同じモデル、ボイス、コアパラメータがすべてに適用されます。違うのは、接続方法、音声がワイヤー上でどのようにフレーミングされるか、そしてタイムスタンプ、継続（ストリーミングされたモデル出力を 1 つの発話に流す）、または 1 つの接続上で多数の生成を扱えるかどうかです。 3 つのエンドポイントすべてが、音声を生成しながらストリーミングします。bytes エンドポイントは、そのストリームを単一の HTTP レスポンスボディとして配信します（プレイグラウンドが使用しているのと同じパターン）。SSE と WebSocket もストリーミングしますが、音声を複数のイベントやメッセージにチャンク分割します。これにより、タイムスタンプなどのチャンクごとのメタデータを運べます。

​

機能比較

発話 (utterance) とは、単一の単位として発音させたい一連の音声（通常は 1 文または UI 文言の 1 行）です。継続 を使うと、その発話を context_id を共有する複数の WebSocket メッセージとして送信できます。詳細は 継続を使った入力ストリーミング と contexts を参照してください。 毎ターンの time-to-first-byte が重要な場合、新しい HTTPS リクエストは TCP と TLS のコストを再度払うことを忘れないでください。そのオーバーヘッドは、音声自体の TTFB と同程度の桁数になることがよくあります。WebSocket はソケットを開いたままにすることで、そのコストを償却します。 SSE は、すでに Server-Sent Events を扱っているスタックや、HTTP のままタイムスタンプが必要な場合のためにサポートを継続しています。音声のみの場合は、bytes の方が通常 HTTP の選択肢として優れています（JSON ラップされたチャンクより小さいエンコーディング）。

​

1 分でエンドポイントを選ぶ

完全なトランスクリプトが事前にわからない場合は、bytes や SSE ではなく、contexts を使った WebSocket を使用してください。

---

​

Bytes (POST /tts/bytes)

バッチジョブ、ファイルキャッシュ、通知、生成あたり 1 回の POST で十分なあらゆる用途に最適です。 レスポンスボディは音声が生成されると同時にストリーミングされます。逐次的に読むことも、最後までバッファすることもできます。多くの出力フォーマットでは、JSON ラップされたチャンクではなく生または file bytes を受け取るため、SSE よりも転送データ量が少なくなります。 典型的なフロー:

1. 完全な transcript、ボイス、モデル、出力フォーマット（WAV、MP3、raw PCM など）を含む 1 つの JSON ペイロード。
2. /tts/bytes に POST する。
3. データが到着するに従ってボディを読むか、完了まで消費する。

1 リクエスト = 1 生成。次の発話には別の POST を送信します。 bytes リファレンス を参照してください。

---

​

SSE (POST /tts/sse)

WebSocket なしで HTTP のままタイムスタンプが必要な場合、またはインテグレーションがすでに SSE を使っている場合に最適です。音声のみ必要で SSE 形式のイベントが不要な場合は、bytes の方が通常シンプルです。それ以外の場合、WebSocket がリアルタイム用途における全機能対応のオプションであり、タイムスタンプもサポートしています。 SSE は主に下位互換性のため、および Server-Sent Events で標準化しているチームのために提供されています。 典型的なフロー:

1. bytes と同じ: 完全なトランスクリプトを含む 1 つの JSON ボディ。
2. /tts/sse に POST する。
3. Server-Sent Events を消費する。各イベントが完了まで次のチャンクを運ぶ。

Bytes と SSE の比較: リクエストごとに完全なトランスクリプトを 1 つ送信する点は変わりません。SSE は WebSocket スタイルの、複数 POST をまたぐ継続をサポートしていません。オプションの context_id はログ用にエコーされるだけで、複数の HTTP リクエストを 1 つの発話にまとめません。テキストを時系列で分割して送信するには WebSocket を使用してください。 SSE リファレンス を参照してください。

---

​

WebSocket (/tts/websocket)

アシスタント、ゲーム、テレフォニー型スタック、または接続が開いたまま時間とともにトランスクリプトテキストが到着する可能性のあるあらゆるケースに最適です。 WebSocket を選ぶ理由:

1. レイテンシー: 接続コストを一度だけ支払い、以降の生成では追加の TCP/TLS ラウンドトリップを回避できます（ターンあたり数十から低い 3 桁 ms 単位）。
2. ストリーミング入力: 到着するに従って断片を送信し（例: LLM から）、その間プロソディを維持できます。継続 と contexts を参照してください。
3. タイムスタンプ: 単語またはセグメントレベルの timing（モデルや言語の制約あり。WebSocket ドキュメント参照）。
4. 多重化: 1 接続上で複数の context_id 値により発話を重ねられます。

典型的なフロー:

1. WebSocket を開く。
2. JSON メッセージを送信する。1 つの発話を複数メッセージに分ける場合、context_id と continue を使い、部分メッセージには continue: true を、その発話の最終部分には continue: false を設定します（最終文字列がまだわからない場合は、contexts の空トランスクリプトパターンを使ってください）。
3. サーバーがそのコンテキストを完了するまで音声を読み取る。

WebSocket リファレンス を参照してください。

---

​

継続

モデルからテキストをストリーミングしていない場合は、継続ではなく bytes か SSE から始めてください。 WebSocket ストリーミングを使う場合は、発話ごとに 1 つの安定した context_id を維持し、すべての部分メッセージに continue: true、その発話の最終メッセージには continue: false を設定してください（contexts を参照）。 テキストやプロソディを壊すもの:

• 連結: チャンクは逐語的に結合されます。スペースが欠けると "...world! How..." ではなく "...world!How..." になります。
• SSML や数値: 一緒に保つべきトークンを分割しないでください（例: SSML 内の小数）。継続ガイド の max_buffer_delay_ms を参照してください。

意図より長く continue: true を維持しても、コンテキストはいずれ自動的に期限切れとなり、音声はサーバールールに従って生成・フラッシュされます。暴走モードにはなりません。それでも、クライアントの状態とサーバーを一致させるため、発話が完了したとわかった時点で continue: false を送信してください。古い context_id 値を無関係な発話に再利用しないでください。

---

​

なぜ WebSocket は context_id を使い、HTTP は使わないのか

POST /tts/bytes と POST /tts/sse では、完全なトランスクリプトを 1 つの JSON ボディで送信します。リクエストをまたぐ継続プロトコルはありません。 context_id と continue は、1 つの発話のテキストが複数メッセージに分かれる WebSocket で重要になります。サーバーは context_id を共有するチャンクを連結します。continue: true は「もっとテキストが来る」を意味し、continue: false はその発話を確定します。 メンタルモデル:

• 1 つの文字列に発話まるごと: bytes か SSE。コンテキスト API なし。
• テキストが断片で到着: WebSocket、発話ごとに 1 つの context_id、継続あり。

---

​

API の使い勝手（全エンドポイント）

• サーバーサイドからの呼び出しでは、クエリ文字列ではなく Authorization ヘッダーで API キーを渡すことを推奨します（ヘッダーはアクセスログに残りにくいため）。ブラウザの WebSocket URL は、プラットフォームに応じて異なるパターンが必要な場合があります。
• モデル ID、ボイス、コア生成パラメータは bytes、SSE、WebSocket で同じです。違うのは、ワイヤーフォーマット、チャンクの公開方法、入力を継続でストリーミングできるかどうかです。

---

​

次に進む