コンテンツにスキップ
RouteAPI RouteAPI

テキスト読み上げ

テキスト読み上げはテキストを読み取り、音声ファイルを返します。OpenAI の音声合成 API に従っており、リクエストボディは JSON、レスポンスボディは音声そのもので、非同期タスクやポーリングの手順はありません。

クライアントの Base URL を /v1 なしで設定している場合も POST /audio/speech を利用できます。ゲートウェイが内部で /v1/audio/speech に書き換えます。

エンドポイント

Section titled “エンドポイント”
POST /v1/audio/speech
https://api.routeapi.ai/v1/audio/speech

リクエストパラメータ

Section titled “リクエストパラメータ”

ボディは JSON です。RouteAPI 自身が検証するのは model のみで、それ以外は上流モデルに転送され、受け付けられる値はそのモデルによって異なります。

フィールドタイプ必須説明
modelstringはいTTS モデル ID（例: tts-1、tts-1-hd、gpt-4o-mini-tts）。ボディに必ず含める必要があり、空または欠落している場合は 400 と Missing required field: model を返します（ルーティングには tts-1 へのフォールバックがありますが、検証が先に実行されます）
inputstring上流で必須合成するテキスト。ゲートウェイは課金のためにこのフィールドから入力トークンも見積もります
voicestring上流で必須音声名。有効な音声のセットはモデルごとに異なります
response_formatstringいいえ音声コンテナ。上流に転送されます。省略した場合は上流のデフォルトが適用されます。ゲートウェイは返された音声の長さを計測して課金するためにもこの値を使用し、省略時は mp3 として扱います。pcm は 24 kHz、16 ビット、モノラルとして計測されます
speednumberいいえ再生速度の倍率。指定された場合はそのまま転送されます
instructionsstringいいえそれをサポートするモデル（gpt-4o-mini-tts など）向けの話し方・スタイルの指示
stream_formatstringいいえsse に設定すると、1 つのバイナリボディではなく Server-Sent Events として音声を受信します。値は転送され、ストリーミング TTS をサポートする上流のみが実際にストリーミングします
metadataobjectいいえ一部のチャネルタイプが自身の上流リクエストにマージする追加フィールド（Volcengine TTS や MiniMax など）

例

Section titled “例”

curl

Section titled “curl”
Terminal window
curl https://api.routeapi.ai/v1/audio/speech \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "voice": "alloy",
    "input": "RouteAPI aggregates many AI providers behind a single API.",
    "response_format": "mp3"
  }' \
  --output speech.mp3

Python（OpenAI SDK）

Section titled “Python（OpenAI SDK）”
import os


from openai import OpenAI


client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)


with client.audio.speech.with_streaming_response.create(
    model="tts-1",
    voice="alloy",
    input="RouteAPI aggregates many AI providers behind a single API.",
    response_format="mp3",
) as response:
    response.stream_to_file("speech.mp3")

client.audio.speech.create(...) も利用でき、生の音声バイト列である response.content を返します。open("speech.mp3", "wb").write(response.content) で保存します。

レスポンス

Section titled “レスポンス”

ボディは JSON ではなく音声ファイルそのものです。ゲートウェイは課金のために上流のボディを読み取って長さを計測し、その後、実際に受け取る内容と一致する Content-Length を付けて出力します。通過する上流ヘッダーは少数の許可リストのみです。特に Content-Type（例: audio/mpeg）はファイル拡張子の判断に利用できます。Server などの他の上流ヘッダーは破棄されます。Content-Encoding は、上流のボディがゲートウェイで展開されていない場合にのみ転送されます。

"stream_format": "sse" を指定すると、レスポンスは text/event-stream になります。各音声チャンクは data: フレームとして到着し、上流が最後に使用量チャンクを送る場合はゲートウェイがそれを課金に使用します。送られない場合は見積もりで課金します。

課金

Section titled “課金”

音声呼び出しは他のすべてのモデル API 呼び出しと同じウォレットとクォータの仕組みで課金されます。見積もりが事前に課金され、上流の応答後に確定し、失敗した呼び出しは返金されます。価格はモデルの設定から取得されます。価格がモデルの詳細ページでどのように表示されるかはモデル料金を参照してください。

どの方法が適用されるかはモデルの価格設定方法によって決まり、モデルの詳細ページに表示されます:

  • リクエストごとの固定料金。 モデルにリクエスト単位の価格が設定されている場合、その価格にグループ倍率を掛けた金額が請求され、トークンは金額に影響しません。組み込みのデフォルトでは gpt-4o-mini-tts がすでにこの方式で設定されています。トークン課金と決めつけずに詳細ページを確認してください。
  • トークン単位。 それ以外の場合は、以下の使用量から課金が計算されます。

入力

Section titled “入力”

入力は input から見積もられます。ゲートウェイはほとんどのモデルで文字数をカウントし、モデル ID に gpt を含むモデルではトークナイザーを使用し、そのカウントにモデルの倍率を掛けて課金します。

出力

Section titled “出力”

生成された音声は 音声 1 分あたり 1000 トークンとして計測されます。ゲートウェイは返された音声から長さを読み取り、ceil(duration) / 60 × 1000 の出力トークンを、モデルの倍率 × 音声倍率 × 音声補完倍率で価格付けします。音声の長さを計測できない場合は、音声 1 キロバイトあたり約 1 トークンにフォールバックします。

tts-1 / tts-1-hd 系の組み込み音声補完倍率は 0 であるため、トークン課金ではこれらのモデルで生成音声分は加算されず、文字ベースの入力が実質的に請求額のすべてになります。音声補完倍率が 0 でないモデルでは、生成音声分も課金されます。

長さの計測は response_format に依存します。pcm はコンテナヘッダーがないため、24 kHz / 16 ビット / モノラルのバイト数から計算されます。他の形式はコンテナから解析されます。

出力トークンは返されたファイルから導出されるため、請求額は input の長さだけではなく、実際に生成された内容に従います。

エラー

Section titled “エラー”

エラーは標準の { "error": { ... } } ボディを使用し、メッセージにはコンソールのログで検索できる request ID が含まれます。完全な一覧はよくあるエラーを参照してください。

ステータスコード原因
400invalid_requestmodel が欠落または空（Missing required field: model）
403insufficient_user_quota / pre_consume_token_quota_failedアカウント残高または Key のクォータが見積もり費用に足りない
403—モデルが Key のモデル許可リスト外（This token has no access to model ...）
429—リクエストのレート制限を超えた
503model_not_foundモデルに利用可能なチャネルがない（No valid upstream service）
500convert_request_failedリクエストをチャネル向けに変換できない。例えばテキスト読み上げを実装していないアダプタのチャネル
4xx / 5xx上流のコードプロバイダがリクエストを拒否しました。ステータスとメッセージはそのまま返されます
{
  "error": {
    "message": "Missing required field: model (request id: 20261023153000123456789AbCdEfGh)",
    "type": "error",
    "code": "invalid_request"
  }
}

リクエストが失敗した場合、事前に課金された金額は返金されます。

次のステップ

Section titled “次のステップ”
  • 音声からテキスト — 音声ファイルを文字起こしまたは翻訳します。
  • モデル — 呼び出す前にモデル ID が Key から見えることを確認します。
  • モデル料金 — 音声の入力価格と出力価格の表示方法。
  • よくあるエラー — ステータスコード、エラーボディ、トラブルシューティングの順序。