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

# TTS

> Convert text to natural speech using AI models, supporting various voice styles and output formats

## Introdução

The Text-to-Speech (TTS) API is based on advanced generative AI models that can convert input text into realistic speech audio. It suporta a variety of use cases:

* Narrating written blog articles
* Gerando speech audio in multiple languages
* Providing real-time audio output streams

## Modelos Disponíveis

### OpenAI Models

* [gpt-4o-audio-preview](https://aihubmix.com/model/gpt-4o-audio-preview) — OpenAI's latest audio generation model, supporting conversational audio generation
* [**gpt-4o-mini-tts**](https://aihubmix.com/model/gpt-4o-mini-tts) — The preferred model for smart real-time applications, supporting advanced voice control and allowing various voice characteristics to be controlled via prompts:
  1. Accent
  2. Emotional range
  3. Intonation
  4. Impressions/Style
  5. Speed of speech
  6. Tone
  7. Whispering
* [**tts-1-hd**](https://aihubmix.com/model/tts-1-hd) — The previous generation TTS model with high-definition audio quality
* [**tts-1**](https://aihubmix.com/model/tts-1) — Standard TTS model, balancing quality and speed

### Gemini Models

* [**gemini-2.5-flash-preview-tts**](https://aihubmix.com/model/gemini-2.5-flash-preview-tts) — Gemini fast TTS model, supporting single and multiple speaker audio generation
* [**gemini-2.5-pro-preview-tts**](https://aihubmix.com/model/gemini-2.5-pro-preview-tts) — Gemini professional TTS model, supporting single and multiple speaker audio generation

**Performance Recommendations:**

1. For the fastest response time, it's recommended to use `wav` or `pcm` as the response format
2. For high-quality audio, use `tts-1-hd`
3. For faster generation speed, use `tts-1`
4. For smart voice applications, `gpt-4o-mini-tts` é recomendado
5. For scenarios requiring multi-speaker dialogues, the Gemini TTS models are recommended

## API Endpoint

### Request URL

```shellscript theme={null}
POST https://aihubmix.com/v1/audio/speech
```

### Headers da Requisição

```shellscript theme={null}
Authorization: Bearer $AIHUBMIX_API_KEY
Content-Type: application/json
```

### Parâmetros da Requisição

#### Standard TTS Parameters

The standard parameters applicable to o seguinte TTS models: tts-1, tts-1-hd, gpt-4o-mini-tts, gemini-2.5-flash-preview-tts, and gemini-2.5-pro-preview-tts.

| Parameter        | Type   | Required | Description                                                                                                                                                                                                              |
| :--------------- | :----- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| model            | string | Sim      | The model ID to be used. Optional values: `tts-1`, `tts-1-hd`, `gpt-4o-mini-tts`, `gemini-2.5-flash-preview-tts`, `gemini-2.5-pro-preview-tts`                                                                           |
| input            | string | Sim      | The text to generate audio from, with a maximum length of 4096 characters                                                                                                                                                |
| voice            | string | Sim      | The voice used for synthesis. See the voice list below.                                                                                                                                                                  |
| response\_format | string | Não      | Audio output format. Supported audio formats include: `mp3`, `opus`, `aac`, `flac`, `wav`, `pcm`, default is `mp3`. `Note: Gemini models only support wav and pcm formats.`                                              |
| speed            | number | Não      | The speed of the generated audio. Range from 0.25 to 4.0, default is 1.0. Note:  `gpt-4o-mini-tts` and `Gemini` models do not support this parameter, but speed can be controlled through natural language descriptions. |
| instructions     | string | Não      | Voice generation instructions, which can specify voice style, intonation, and emotional characteristics in detail, applicable only for `gpt-4o-mini-tts` and `Gemini` models.                                            |

#### gpt-4o-audio-preview Parameters

| Parameter  | Type   | Required | Description                                                       |
| :--------- | :----- | :------- | :---------------------------------------------------------------- |
| model      | string | Sim      | Set to `gpt-4o-audio-preview`                                     |
| modalities | array  | Sim      | Set to `["text", "audio"]` to enable audio output                 |
| audio      | object | Sim      | Audio configuration object containing `voice` and `format` fields |
| messages   | array  | Sim      | Array of chat messages, similar to standard chat format           |

## Voice List

### OpenAI Voices

Suporta o seguinte voice options:

* **alloy** - Neutral, balanced
* **ash** - Clear, professional
* **ballad** - Warm, narrative
* **coral** - Friendly, approachable
* **echo** - Clear, bright
* **fable** - Expressive, dramatic
* **onyx** - Deep, authoritative
* **nova** - Lively, energetic
* **sage** - Mature, knowledgeable
* **shimmer** - Soft, soothing
* **verse** - Clear, versatile
* **marin** - Natural, friendly
* **cedar** - Stable, reliable

### Gemini Voices

Suporta o seguinte 30 voice options:

| Voice Name    | Style        | Voice Name        | Style           | Voice Name       | Style         |
| :------------ | :----------- | :---------------- | :-------------- | :--------------- | :------------ |
| **Zephyr**    | *Bright*     | **Puck**          | *Upbeat*        | **Charon**       | *Informative* |
| **Kore**      | *Firm*       | **Fenrir**        | *Excitable*     | **Leda**         | *Youthful*    |
| **Orus**      | *Firm*       | **Aoede**         | *Breezy*        | **Callirrhoe**   | *Easy-going*  |
| **Autonoe**   | *Bright*     | **Enceladus**     | *Breathy*       | **Iapetus**      | *Clear*       |
| **Umbriel**   | *Easy-going* | **Algieba**       | *Smooth*        | **Despina**      | *Smooth*      |
| **Erinome**   | *Clear*      | **Algenib**       | *Gravelly*      | **Rasalgethi**   | *Informative* |
| **Laomedeia** | *Upbeat*     | **Achernar**      | *Soft*          | **Alnilam**      | *Firm*        |
| **Schedar**   | *Even*       | **Gacrux**        | *Mature*        | **Pulcherrima**  | *Forward*     |
| **Achird**    | *Friendly*   | **Zubenelgenubi** | *Casual*        | **Vindemiatrix** | *Gentle*      |
| **Sadachbia** | *Lively*     | **Sadaltager**    | *Knowledgeable* | **Sulafat**      | *Warm*        |

### Voice Mapping

When using Gemini models, if an OpenAI voice name is provided, the system will automatically map it to the corresponding Gemini voice:

| OpenAI Voice | Gemini Voice | OpenAI Voice | Gemini Voice |
| :----------- | :----------- | :----------- | :----------- |
| alloy        | Kore         | ash          | Fenrir       |
| ballad       | Aoede        | coral        | Leda         |
| echo         | Puck         | fable        | Zephyr       |
| onyx         | Charon       | nova         | Orus         |
| sage         | Algieba      | shimmer      | Callirrhoe   |
| verse        | Enceladus    | marin        | Despina      |
| cedar        | Iapetus      |              |              |

## Usage Examples

### Standard TTS Model (OpenAI)

```curl theme={null}
curl https://aihubmix.com/v1/audio/speech \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "The quick brown fox jumped over the lazy dog.",
    "voice": "alloy"
  }' \
  --output speech.mp3
```

### Gemini TTS Model (Single Speaker)

```curl theme={null}
curl https://aihubmix.com/v1/audio/speech \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-preview-tts",
    "input": "Say cheerfully: Have a wonderful day!",
    "voice": "Kore",
    "response_format": "wav"
  }' \
  --output speech.wav
```

### Gemini TTS Model (Multi-Speaker - Controlled by Prompts)

```curl theme={null}
curl https://aihubmix.com/v1/audio/speech \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-preview-tts",
    "input": "TTS the following conversation between Joe and Jane:\nJoe: How'\''s it going today Jane?\nJane: Not too bad, how about you?",
    "voice": "Kore",
    "response_format": "wav",
    "instructions": "Joe should sound firm and professional, Jane should sound upbeat and friendly"
  }' \
  --output conversation.wav
```

### Python Example (OpenAI SDK)

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="your-aihubmix-api-key",
    base_url="https://aihubmix.com/v1"
)

response = client.audio.speech.create(
    model="tts-1",
    voice="alloy",
    input="The quick brown fox jumped over the lazy dog."
)

response.stream_to_file("speech.mp3")
```

### Python Example (Gemini TTS)

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="your-aihubmix-api-key",
    base_url="https://aihubmix.com/v1"
)

# Single Speaker
response = client.audio.speech.create(
    model="gemini-2.5-flash-preview-tts",
    voice="Kore",
    input="Say cheerfully: Have a wonderful day!",
    extra_body={
        "response_format": "wav"
    }
)

response.stream_to_file("speech.wav")

# Multi-Speaker Dialogue
conversation_response = client.audio.speech.create(
    model="gemini-2.5-flash-preview-tts",
    voice="Kore",
    input="""TTS the following conversation between Joe and Jane:
    Joe: How's it going today Jane?
    Jane: Not too bad, how about you?""",
    extra_body={
        "response_format": "wav",
        "instructions": "Joe should sound firm, Jane should sound upbeat"
    }
)

conversation_response.stream_to_file("conversation.wav")
```

## Controlling Voice Style (Gemini Models)

Gemini TTS models support controlling voice style, tone, accent, and speed through natural language prompts. Você pode provide guidance no `input` or `instructions` parameters.

### Single Speaker Style Control

```json theme={null}
{
  "model": "gemini-2.5-flash-preview-tts",
  "input": "Say in a spooky whisper: By the pricking of my thumbs... Something wicked this way comes",
  "voice": "Enceladus",
  "response_format": "wav"
}
```

### Multi-Speaker Style Control

```json theme={null}
{
  "model": "gemini-2.5-flash-preview-tts",
  "input": "Speaker1: So... what's on the agenda today?\nSpeaker2: You're never going to guess!",
  "voice": "Kore",
  "response_format": "wav",
  "instructions": "Make Speaker1 sound tired and bored, and Speaker2 sound excited and happy"
}
```

### Prompt Structure Recommendations

For best results, você pode use o seguinte structured prompt format:

```json theme={null}
{
  "model": "gemini-2.5-flash-preview-tts",
  "input": "Your transcript here",
  "voice": "Kore",
  "instructions": "# AUDIO PROFILE: Character Name\n## Role Description\n\n## THE SCENE: Scene Name\nDescribe the environment and mood\n\n### DIRECTOR'S NOTES\nStyle: Describe the style\nPacing: Describe the pacing\nAccent: Specify the accent"
}
```

## Supported Languages

The TTS models automatically detect the input language. O seguinte 24 languages are supported:

| Language               | BCP-47 Code   | Language             | BCP-47 Code |
| :--------------------- | :------------ | :------------------- | :---------- |
| Arabic (Egypt)         | ar-EG         | German (Germany)     | de-DE       |
| English (US)           | en-US         | Spanish (US)         | es-US       |
| French (France)        | fr-FR         | Hindi (India)        | hi-IN       |
| Indonesian (Indonesia) | id-ID         | Italian (Italy)      | it-IT       |
| Japanese (Japan)       | ja-JP         | Korean (South Korea) | ko-KR       |
| Portuguese (Brazil)    | pt-BR         | Russian (Russia)     | ru-RU       |
| Dutch (Netherlands)    | nl-NL         | Polish (Poland)      | pl-PL       |
| Thai (Thailand)        | th-TH         | Turkish (Turkey)     | tr-TR       |
| Vietnamese (Vietnam)   | vi-VN         | Romanian (Romania)   | ro-RO       |
| Ukrainian (Ukraine)    | uk-UA         | Bengali (Bangladesh) | bn-BD       |
| English (India)        | en-IN & hi-IN | Marathi (India)      | mr-IN       |
| Tamil (India)          | ta-IN         | Telugu (India)       | te-IN       |

## Response Formats

### Audio Formats

| Format | Content-Type | Description                         | Model Support |
| :----- | :----------- | :---------------------------------- | :------------ |
| mp3    | audio/mpeg   | Default format, widely compatible   | OpenAI Models |
| opus   | audio/opus   | Suitable for internet streaming     | OpenAI Models |
| aac    | audio/aac    | Digital audio compression           | OpenAI Models |
| flac   | audio/flac   | Lossless audio compression          | OpenAI Models |
| wav    | audio/wav    | Uncompressed WAV audio              | All Models    |
| pcm    | audio/pcm    | Raw PCM audio (24kHz, mono, 16-bit) | All Models    |

**Note:** The Gemini model natively returns PCM format (24kHz, mono, 16-bit), and the system will automatically convert it to WAV format. For other formats, it's recommended to use OpenAI models.

### Response Body

On success, an audio stream (binary data) is returned, and Content-Type is set according to the `response_format` parameter.

On failure, a JSON error message is returned:

```json theme={null}
{
  "error": {
    "message": "Error description",
    "type": "error_type",
    "code": "error_code"
  }
}
```

## Billing Information

The TTS API is billed based on the number of characters:

* The character count of the input text is the billing unit
* Different models have different price multipliers
* Maximum input length: 4096 characters

## Limitações

* Maximum input length: 4096 characters
* Gemini TTS models only support `wav` and `pcm` output formats
* Gemini TTS models do not support the `speed` parameter (controlled through prompts)
* Context window limit: 32k tokens (Gemini models)

## Perguntas Frequentes

### Q: How do I escolha the right model?

* Need quick generation → `tts-1` or `gemini-2.5-flash-preview-tts`
* Need high-quality audio → `tts-1-hd`
* Need intelligent voice control → `gpt-4o-mini-tts` or Gemini TTS models
* Need multi-speaker dialogues → Gemini TTS models

### Q: What are the differences between Gemini TTS and OpenAI TTS?

* **Gemini TTS**: Suporta controlling voice style through natural language prompts, suporta multiple speakers, but only WAV/PCM formats
* **OpenAI TTS**: Suporta multiple audio formats, has fixed voice options, and speed can be controlled via parameters

### Q: How do I implement multi-speaker dialogues?

Use the Gemini TTS model, format the `input` as a dialogue, and specify the style for each speaker no `instructions`:

```json theme={null}
{
  "model": "gemini-2.5-flash-preview-tts",
  "input": "Speaker1: Hello!\nSpeaker2: Hi there!",
  "instructions": "Speaker1 should sound professional, Speaker2 should sound casual"
}
```

### Q: Is streaming output supported?

## Atualmente, the TTS API returns complete audio files and não suporta streaming output.

Última atualização: 2026-06-01