> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TTS エンドポイントの比較

> bytes、SSE、WebSocket がテキスト読み上げでどう異なるか、それぞれをいつ使うか。

Cartesia は、テキストを音声に変換する 3 つの方法を提供します。同じモデル、ボイス、コアパラメータがすべてに適用されます。違うのは、接続方法、音声がワイヤー上でどのようにフレーミングされるか、そしてタイムスタンプ、継続（ストリーミングされたモデル出力を 1 つの発話に流す）、または 1 つの接続上で多数の生成を扱えるかどうかです。

3 つのエンドポイントすべてが、音声を生成しながらストリーミングします。bytes エンドポイントは、そのストリームを単一の HTTP レスポンスボディとして配信します（プレイグラウンドが使用しているのと同じパターン）。SSE と WebSocket もストリーミングしますが、音声を複数のイベントやメッセージにチャンク分割します。これにより、タイムスタンプなどのチャンクごとのメタデータを運べます。

## 機能比較

|           | 1 接続あたりの複数生成          | タイムスタンプ | 継続  |
| --------- | --------------------- | ------- | --- |
| WebSocket | はい                    | はい      | はい  |
| Bytes     | いいえ（生成ごとに 1 回 `POST`） | いいえ     | いいえ |
| SSE       | いいえ（生成ごとに 1 回 `POST`） | はい      | いいえ |

**発話 (utterance)** とは、単一の単位として発音させたい一連の音声（通常は 1 文または UI 文言の 1 行）です。**継続** を使うと、その発話を `context_id` を共有する複数の WebSocket メッセージとして送信できます。詳細は [継続を使った入力ストリーミング](/build-with-cartesia/capability-guides/stream-inputs-using-continuations) と [contexts](/use-the-api/tts-websocket/contexts) を参照してください。

```mermaid theme={null}
flowchart TD
    Q1{"Are you streaming text from an LLM<br>or other partial input?"}
    Q2{"Do you need timestamps on HTTP<br>without WebSocket?"}
    Q3{"Will you speak often enough that<br>repeated connect/TLS cost hurts?"}
    WS["WebSocket"]
    SSE["SSE"]
    Bytes["Bytes"]

    Q1 -- "Yes" --> WS
    Q1 -- "No" --> Q2
    Q2 -- "Yes" --> SSE
    Q2 -- "No" --> Q3
    Q3 -- "Yes" --> WS
    Q3 -- "No" --> Bytes
```

毎ターンの time-to-first-byte が重要な場合、新しい HTTPS リクエストは TCP と TLS のコストを再度払うことを忘れないでください。そのオーバーヘッドは、音声自体の TTFB と同程度の桁数になることがよくあります。WebSocket はソケットを開いたままにすることで、そのコストを償却します。

SSE は、すでに Server-Sent Events を扱っているスタックや、HTTP のままタイムスタンプが必要な場合のためにサポートを継続しています。音声のみの場合は、bytes の方が通常 HTTP の選択肢として優れています（JSON ラップされたチャンクより小さいエンコーディング）。

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

| 作っているもの                                                                        | 使うもの                                                       | 短いラベル                               |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------- | ----------------------------------- |
| 完全なトランスクリプトを 1 リクエストで送信し、ストリーミング HTTP ボディが欲しい（効率的、プレイグラウンドと同じパターン）             | [`POST /tts/bytes`](/api-reference/tts/bytes)              | Stream speech (bytes)               |
| 完全なトランスクリプトを 1 リクエストで送信し、WebSocket なしでタイムスタンプが必要、またはスタックが既に SSE を使っている         | [`POST /tts/sse`](/api-reference/tts/sse)                  | Stream speech with timestamps (SSE) |
| 長時間セッション、部分的なトランスクリプト（例: LLM トークン）、多数のターンにわたる最低レイテンシー、タイムスタンプ、または 1 ソケット上の複数発話 | [WebSocket `/tts/websocket`](/api-reference/tts/websocket) | Live session (WebSocket)            |

完全なトランスクリプトが事前にわからない場合は、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 リファレンス](/api-reference/tts/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 の比較:

|         | Bytes                                | SSE                                |
| ------- | ------------------------------------ | ---------------------------------- |
| 形状      | 1 つのストリーミングレスポンスボディ（生または file bytes） | 多数の SSE イベント（多くは JSON と base64 音声） |
| タイムスタンプ | いいえ                                  | はい（イベントペイロード内）                     |

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

[SSE リファレンス](/api-reference/tts/sse) を参照してください。

***

## WebSocket (`/tts/websocket`)

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

WebSocket を選ぶ理由:

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

典型的なフロー:

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

[WebSocket リファレンス](/api-reference/tts/websocket) を参照してください。

***

## 継続

モデルからテキストをストリーミングしていない場合は、継続ではなく bytes か SSE から始めてください。

WebSocket ストリーミングを使う場合は、発話ごとに 1 つの安定した `context_id` を維持し、すべての部分メッセージに `continue: true`、その発話の最終メッセージには `continue: false` を設定してください（[contexts](/use-the-api/tts-websocket/contexts) を参照）。

テキストやプロソディを壊すもの:

* 連結: チャンクは逐語的に結合されます。スペースが欠けると `"...world! How..."` ではなく `"...world!How..."` になります。
* SSML や数値: 一緒に保つべきトークンを分割しないでください（例: SSML 内の小数）。[継続ガイド](/build-with-cartesia/capability-guides/stream-inputs-using-continuations) の `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 で同じです。違うのは、ワイヤーフォーマット、チャンクの公開方法、入力を継続でストリーミングできるかどうかです。

***

## 次に進む

<CardGroup cols={3}>
  <Card title="音声をストリーミング (bytes)" icon="download" href="/api-reference/tts/bytes">
    1 つの POST、ストリーミングレスポンスボディ
  </Card>

  <Card title="タイムスタンプ付き音声ストリーミング (SSE)" icon="waveform" href="/api-reference/tts/sse">
    タイムスタンプと SSE チャンク音声
  </Card>

  <Card title="ライブセッション (WebSocket)" icon="plug" href="/api-reference/tts/websocket">
    入力ストリーミング、多重化、ターンにわたる最低レイテンシー
  </Card>
</CardGroup>