> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Speech

> Generates audio from the input text

<Note>
  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.
</Note>

## 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.

<ParamField body="model" type="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.
</ParamField>

<ParamField body="input" type="string" required>
  The text to generate audio for. Maximum 4096 characters.
</ParamField>

<ParamField body="voice" type="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.
</ParamField>

<ParamField body="voice_id" type="string">
  Provider-native voice selector for MiniMax-compatible speech models.
</ParamField>

<ParamField body="instructions" type="string">
  Optional style or delivery instructions for OpenAI-compatible TTS models that support them.
</ParamField>

<ParamField body="prompt" type="string">
  Optional speaking style prompt for Gemini TTS models.
</ParamField>

<ParamField body="language_code" type="string">
  Optional language code, for example `en-US`, for Gemini, xAI, and compatible TTS routes.
</ParamField>

<ParamField body="response_format" type="string">
  Audio format. Common values include `mp3`, `opus`, `aac`, `flac`, `wav`, and `pcm`; supported values vary by model family.
</ParamField>

<ParamField body="stream_format" type="string" default="audio">
  TokenLab delivery format: `audio` or `sse`. `stream_format=sse` is not supported for `tts-1` or `tts-1-hd`.
</ParamField>

<ParamField body="speed" type="number">
  Speech speed for model families that support it (0.25 to 4.0).
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature for Gemini-compatible TTS routes (0 to 2).
</ParamField>

## Response

Returns the audio file in the requested format.

<RequestExample>
  ```bash cURL theme={null}
  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
  ```

  ```python Python theme={null}
  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")
  ```

  ```javascript JavaScript theme={null}
  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 PHP theme={null}
  <?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);
  ```
</RequestExample>

## Voice Samples

| Voice     | Description           |
| --------- | --------------------- |
| `alloy`   | Neutral, balanced     |
| `ash`     | Calm, measured        |
| `ballad`  | Melodic, expressive   |
| `coral`   | Warm, inviting        |
| `echo`    | Warm, conversational  |
| `fable`   | Expressive, narrative |
| `nova`    | Friendly, clear       |
| `onyx`    | Deep, authoritative   |
| `sage`    | Wise, thoughtful      |
| `shimmer` | Soft, gentle          |
| `verse`   | Dynamic, versatile    |

## Response example

<ResponseExample>
  ```binary 200 OK theme={null}
  <binary audio data>
  ```
</ResponseExample>

## Important fields

<ResponseField name="Content-Type" type="string">Event or message type returned by the API.</ResponseField>
<ResponseField name="body" type="binary">Raw response body. Save it directly instead of parsing it as JSON.</ResponseField>