メインコンテンツへスキップ
Cartesia はストリーミング TTS で 2 つのバッファリングモードをサポートします: マネージドバッファリングとカスタムバッファリングです。適切な選択は、プロソディとレイテンシーのトレードオフをどれだけ制御したいかによって異なります。
マネージドバッファリングから始めてください。 最小限の統合工数で自然に聞こえる音声が得られます。きめ細かな制御が必要な場合のみカスタムバッファリングに切り替えてください。

​
マネージドバッファリング

LLM トークンを Cartesia に直接ストリーミングし、API に音声生成を開始するタイミングを決めさせます。これは Cartesia のマネージドボイスエージェントプラットフォームで使われているのと同じアプローチです。 max_buffer_delay_ms を 0 より大きい値（デフォルトは 3000ms）に設定し、テキストをトークン単位でストリーミングします。 
{
  "model_id": "sonic-3.5",
  "transcript": "Hello",
  "voice": {
    "mode": "id",
    "id": "a0e99841-438c-4a64-b679-ae501e7d6091"
  },
  "context_id": "my-context",
  "continue": true,
  "max_buffer_delay_ms": 3000
}
API は、高品質な音声を生成するのに十分なコンテキストが集まるか、max_buffer_delay_ms が経過するかのいずれか早い方まで、入ってくるテキストをバッファします。これにより、レイテンシーを最適化しつつ、文単位での集約と同等の結果が得られます。 マネージドバッファリングを使う場面:
  • LLM 出力をトークン単位でストリーミングしている
  • バッファリングロジックを構築せずに自然に聞こえる音声が欲しい
  • 良いデフォルトで簡単な統合をしたい

​
カスタムバッファリング

バッファリングを自分で処理し、完全なフレーズや文を Cartesia に送信します。max_buffer_delay_ms を 0 に設定すると、API は受け取ったものから即座に音声を生成します。 
{
  "model_id": "sonic-3.5",
  "transcript": "Hello, my name is Sonic.",
  "voice": {
    "mode": "id",
    "id": "a0e99841-438c-4a64-b679-ae501e7d6091"
  },
  "context_id": "my-context",
  "continue": true,
  "max_buffer_delay_ms": 0
}
カスタムバッファリングでは、プロソディとレイテンシーのトレードオフを直接制御できます:
  • 完全な文 は最高のプロソディを生み出しますが、文が完成するのを待つためレイテンシーが増えます。
  • 部分文 はレイテンシーを下げますが、チャンクの境界で自然さに欠ける音声になる可能性があります。
カスタムバッファリングを使う場面:
  • 音声生成を開始するタイミングを正確に制御したい
  • 独自の文検出やテキスト集約ロジックがある
  • 特定のレイテンシー目標に最適化したい

​
中途半端な状態を避ける

よくある間違いは、クライアント側でテキストを文やフレーズに集約し、かつ デフォルトの max_buffer_delay_ms 3000ms を使うことです。これは不要なレイテンシーを引き起こす可能性があります。完全な文を受信した後、API は音声を生成する前に追加入力を最大 3000ms 待つ可能性があるためです。 どちらか一方を選択してください:
  • マネージドバッファリング: max_buffer_delay_ms > 0 でトークンをストリーミングし、Cartesia に集約を任せる。
  • カスタムバッファリング: テキストを自分で集約し、max_buffer_delay_ms = 0 を設定する。

​
設定リファレンス

​
max_buffer_delay_ms
number
デフォルト:"3000"
バッファされたテキストから音声を生成する前に、API が追加入力を待つ最大時間（ミリ秒）。
  • 範囲: 0〜5000ms
  • デフォルト: 3000ms
  • カスタムバッファリング（サーバー側バッファリングなし）にする場合は 0 に設定
  • マネージドバッファリングにする場合は > 0 に設定
マネージドバッファリングで speed や volume の SSML タグ を使う場合は、小数値がトークン間で分割されないように注意してください。1.0 を 1、.、0 として送信するとパースエラーになります。

​
最良の結果を得るためのヒント

  • 文を句読点で終わらせる。 終端の句読点（.、?、!）がない場合、モデルはテキストを未完了として扱い、生成前にバッファ遅延の経過を待つ可能性があります。詳細は 継続を使った入力ストリーミング を参照してください。
  • 入力完了を通知する。 ターンが完了したら、continue: false（WebSocket）または no_more_inputs()（SDK）を使って、モデルが追加テキストを待たないようにします。
  • 現実的な入力パターンでテストする。 バッファリングの挙動はテキストの到着方法に依存します。事前に書かれたテキストではなく、実際の LLM 出力でテストしてください。