Skip to main content
For coding agents, discover the current recommended TTS shortlist first with GET /v1/models?recommended_for=tts, then send the selected model explicitly to this endpoint.

Request Body

Synchronous request timeout: This non-chat endpoint waits for the routed model to finish. Large inputs, long audio, or large batches can exceed common 30s client defaults, so set your HTTP client timeout to at least 120s. Supported optional fields vary by model family. TokenLab validates this field matrix before routing: OpenAI TTS accepts voice, instructions, response_format, stream_format, and speed; MiniMax speech accepts voice, voice_id, response_format, stream_format, and speed; Gemini TTS accepts prompt, language_code, voice, response_format, stream_format, speed, and temperature; narrower Vidu/Kling-style TTS routes may accept only input and stream_format. Unknown top-level fields, including user, return 400 unsupported_parameter instead of being ignored.
model
string
default:"tts-1"
TTS model. Examples include tts-1, gpt-4o-mini-tts, speech-02-hd, and gemini-2.5-flash-tts. Query GET /v1/models?recommended_for=tts for the current shortlist.
input
string
required
The text to generate audio for. Maximum 4096 characters.
voice
string | object
Voice selector. Pass a built-in voice name such as nova, a Gemini voice such as Kore, or an object like { "id": "voice-id" } for compatible custom voices.
voice_id
string
Provider-native voice selector for MiniMax-compatible speech models.
instructions
string
Optional style or delivery instructions for OpenAI-compatible TTS models that support them.
prompt
string
Optional speaking style prompt for Gemini TTS models.
language_code
string
Optional language code, for example en-US, for Gemini, xAI, and compatible TTS routes.
response_format
string
Audio format. Common values include mp3, opus, aac, flac, wav, and pcm; supported values vary by model family.
stream_format
string
default:"audio"
TokenLab delivery format: audio or sse. stream_format=sse is not supported for tts-1 or tts-1-hd.
speed
number
Speech speed for model families that support it (0.25 to 4.0).
temperature
number
Sampling temperature for Gemini-compatible TTS routes (0 to 2).

Response

Returns the audio file in the requested format.
curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1-hd",
    "voice": "nova",
    "input": "Hello, welcome to TokenLab!"
  }' \
  --output speech.mp3
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.tokenlab.sh/v1"
)

response = client.audio.speech.create(
    model="tts-1-hd",
    voice="nova",
    input="Hello, welcome to TokenLab!"
)

response.stream_to_file("speech.mp3")
import OpenAI from 'openai';
import fs from 'fs';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.tokenlab.sh/v1'
});

const response = await client.audio.speech.create({
  model: 'tts-1-hd',
  voice: 'nova',
  input: 'Hello, welcome to TokenLab!'
});

const buffer = Buffer.from(await response.arrayBuffer());
fs.writeFileSync('speech.mp3', buffer);
<?php
$ch = curl_init('https://api.tokenlab.sh/v1/audio/speech');

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer sk-your-api-key'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'model' => 'tts-1-hd',
        'voice' => 'nova',
        'input' => 'Hello, welcome to TokenLab!'
    ])
]);

$audio = curl_exec($ch);
curl_close($ch);

file_put_contents('speech.mp3', $audio);

Voice Samples

VoiceDescription
alloyNeutral, balanced
ashCalm, measured
balladMelodic, expressive
coralWarm, inviting
echoWarm, conversational
fableExpressive, narrative
novaFriendly, clear
onyxDeep, authoritative
sageWise, thoughtful
shimmerSoft, gentle
verseDynamic, versatile

Response example

<binary audio data>

Important fields

Content-Type
string
Event or message type returned by the API.
body
binary
Raw response body. Save it directly instead of parsing it as JSON.