Text-to-Speech

Request body

Response

Returns audio bytes with the appropriate Content-Type header (e.g. audio/mpeg for mp3). Status 200 on success.

Quick start

from openai import OpenAI

client = OpenAI(
    base_url="https://api.therouter.ai",
    api_key="YOUR_API_KEY",
)

with client.audio.speech.with_streaming_response.create(
    model="openai/tts-1",
    voice="alloy",
    input="Hello from TheRouter.ai!",
) as response:
    response.stream_to_file("output.mp3")

CJK / Chinese text

For Chinese and other CJK text, use alibaba/cosyvoice2-0.5b (SiliconFlow). It is billed per UTF-8 byte rather than per character, making CJK billing proportional to actual data size. The fallback from openai/tts-1 to CosyVoice2 is automatic when the OpenAI provider is unavailable.

# SiliconFlow CosyVoice2 — optimised for Chinese text
# Billed per UTF-8 byte (3 bytes per CJK character)
response = client.audio.speech.create(
    model="alibaba/cosyvoice2-0.5b",
    voice="alloy",
    input="你好，欢迎使用 TheRouter！",
)

Supported models

Voice cloning

Some models can synthesise speech in a voice you supply rather than a preset one. Send reference_audio instead of voice:

Upload the clip to TheRouter first, then reference it by id. Your audio is stored by us and sent to the provider from our storage — we never hand a provider a URL of yours to fetch.

# 1. Upload the clip (same endpoint you already use for images)
curl https://api.therouter.ai/v1/files \
  -H "Authorization: Bearer $THEROUTER_API_KEY" \
  -F purpose=user_data \
  -F file=@my-voice.mp3
# -> { "id": "file_abc123", ... }

# 2. Synthesise in that voice
curl https://api.therouter.ai/v1/audio/speech \
  -H "Authorization: Bearer $THEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "indexteam/indextts-2",
    "input": "The text you want spoken.",
    "reference_audio": {
      "file_id": "file_abc123",
      "text": "Exact transcript of the clip."
    }
  }' --output cloned.mp3

For a small clip you can skip the upload and inline it instead, as "audio": "data:audio/mp3;base64,...". A URL is not accepted in either field.

Discover support and limits per model from GET /v1/audio/models — a cloning-capable model carries a reference_audio block naming its accepted formats, maximum clip duration, and whether a transcript is required. For indexteam/indextts-2 today that is MP3 or WAV, at most 30 seconds (8–10 seconds is what the model does best with), transcript required.

Your clip is validated before the request reaches a provider, so an unsupported format, an over-long clip or a missing transcript comes back as a 400 naming the limit — and is not billed. A cloning request is never quietly downgraded to a preset voice: if no available route can clone, the request fails rather than returning a different voice than you asked for.

Reusable voices

Sending the clip on every request is wasteful if you always use the same voice. Create it once and refer to it by id:

# Create a voice from an uploaded clip
curl https://api.therouter.ai/v1/audio/voices \
  -H "Authorization: Bearer $THEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "indexteam/indextts-2",
    "name": "Narrator",
    "reference_audio": { "file_id": "file_abc123", "text": "Transcript of the clip." }
  }'
# -> { "id": "voice_9f2c...", "object": "audio.voice", "name": "Narrator", ... }

# Then just name it
curl https://api.therouter.ai/v1/audio/speech \
  -H "Authorization: Bearer $THEROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "indexteam/indextts-2",
    "input": "Anything you like, in that voice.",
    "voice": "voice_9f2c..."
  }' --output narrated.mp3

curl https://api.therouter.ai/v1/audio/voices   # list yours
curl -X DELETE https://api.therouter.ai/v1/audio/voices/voice_9f2c...

A voice belongs to the account that created it and is usable only with the model it was created for. Up to 50 voices per account; delete one to make room.

Creating a voice is not billed on any model we currently serve — you pay for synthesis, as usual.