Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt

Use this file to discover all available pages before exploring further.

このドキュメントは英語の原文から自動翻訳されています。表現に不自然な箇所がある場合があります。正確な内容は英語の原文もあわせてご確認ください。
stream_speech はオーディオをチャンク単位で返すため、クリップ全体の生成完了 に再生や転送を開始できます。パスは /v1/text-to-speech/{voice_id}/stream です。
ストリーミングは現時点では sona_speech_1 のみ対応しています。

ストリーミングを使うべき場面

ストリーミングは、1 つの TTS クリップが、最後まで待つと体感できるほど長い場合にもっとも有効です — たとえば、複数文からなる段落を 1 回の呼び出しで合成するケースです。 対話型エージェントやチャットボット のように、各発話が短い 1 文である場合は、高速な非ストリーミングモデルを使うほうがトータルのレイテンシが小さくなるのが一般的です。
  • sona_speech_2_flash — 速度と品質のバランスが取れています。
  • supertonic_api_3 — 推論がもっとも高速で、発話の安定性も高いモデルです。time-to-first-audio が最優先のときに利用してください。
詳しい議論は レイテンシ最適化 をご覧ください。LLM レスポンスから TTS をストリーミングする で紹介している文単位のパターンは、stream_speech を一切使いません — 文ごとに高速な非ストリーミングモデルを呼び出す方式に基づいています。

基本のストリーミング

from supertone import Supertone

VOICE_ID = "20160a4c5ba38967330c84"  # replace with your voice ID

with Supertone(api_key=API_KEY) as client:
    response = client.text_to_speech.stream_speech(
        voice_id=VOICE_ID,
        text="This response is streamed chunk by chunk.",
        language="en",
        model="sona_speech_1",
        output_format="wav",
    )

    with open("streamed.wav", "wb") as f:
        for chunk in response.result.iter_bytes():
            f.write(chunk)

リクエストフィールド

Create speech と同じです。ただし modelsona_speech_1(現在ストリーミングに対応している唯一のモデル)に固定されます。パスは /v1/text-to-speech/{voice_id}/stream です。

レスポンス

デフォルトでは、レスポンスボディは バイナリオーディオストリーム で、Content-Typeoutput_format に対応します。
  • audio/wav — WAV ファイルのチャンク(最初のチャンクに WAV ヘッダーが含まれます)。
  • audio/mpeg — MP3 ファイルのチャンク。
include_phonemes=true の場合、レスポンスは NDJSON に切り替わり、1 行ごとに 1 つの JSON オブジェクト(Base64 オーディオチャンクと対応する音素データを含む)が返されます。

長い入力のストリーミング

SDK はストリーミング時でも 300 文字を超えるテキストを自動的にチャンク分割します。内部ではテキストを分割し、順次ストリーミングリクエストを送信し、呼び出し側のイテレータにチャンクを転送します — そのため、読み取りループ側のコードは変わりません。 詳細は Long text をご覧ください。

ヒント

  • プレイヤーのバッファリング。 ほとんどのプレイヤーは再生開始前にある程度のバッファを必要とします。最初のチャンクをすぐ再生するより、1〜2 秒バッファリングしてから再生したほうがスムーズに感じられます。
  • WAV と MP3。 WAV チャンクはサイズが大きくなりますが連結しやすく、MP3 ストリームはサイズが小さく低速ネットワークでの配信に向いています。
  • エラーハンドリング。 ストリームエラーは読み取りの途中で発生することがあります — 通常のエラーハンドラでイテレーションを包み、特に一時的な 4295xx レスポンスに対してはリトライできるようにしてください。リトライとバックオフ を参照してください。

関連項目

LLM ストリーミング TTS

ボイスエージェント向けの文単位パターン。

レイテンシ最適化

低レイテンシのためのモデルとパターンの選び方。