# Text to speech

> Speech generation.

Speech generation.

When and why to call these: the [text to speech guide](https://docs.lumavox.ai/speech/text-to-speech.md).

## Generate speech

`POST /v1/tts`

Synthesize speech from text with the chosen model and voice. Returns complete audio as WAV, or a chunked stream when `stream: true` (pcm only).

```bash title="curl"
curl -X POST "https://api.lumavox.ai/v1/tts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"..."}'
```

**Request body** (`application/json`)

| Field | Type | Required | Description |
|---|---|---|---|
| `voice_id` | string |  | An id from `GET /v1/voices` — the built-in voice, a platform voice, or one your organisation uploaded. Default `"default"`. |
| `model` | string |  | Which model speaks: one of the voice's `models` in `GET /v1/voices` — `eleven_flash_v2_5` (the fastest, and the default), `eleven_multilingual_v2` or `eleven_v3`. A model the voice does not list is refused. Default `"eleven_flash_v2_5"`. |
| `provider_options` | ProviderVoiceSettings or null |  | The provider's voice settings, on top of the ones the voice was registered with. Unset takes theirs. |
| `provider_options.stability` | number or null |  | Low is more expressive and less consistent between generations; high is flatter and more repeatable. 0–1. |
| `provider_options.similarity_boost` | number or null |  | How closely to cling to the original voice. High can reproduce artefacts in the source. 0–1. |
| `provider_options.style` | number or null |  | Style exaggeration. Costs latency; leave unset on anything conversational. 0–1. |
| `provider_options.use_speaker_boost` | boolean or null |  | Similarity at the cost of latency. |
| `provider_options.speed` | number or null |  | 1.0 is the voice's own pace. 0.7–1.2. |
| `format` | `"wav"`, `"pcm"` |  | Output audio format Default `"wav"`. |
| `sample_rate` | `8000`, `16000`, `22050`, `24000`, `44100` or null |  | Hz of the returned audio — one of 8000, 16000, 22050, 24000, 44100, each served natively by the provider. Unset means 24000. `POST /v1/tts` says what it produced in the `X-Sample-Rate` header. Queued speech (`POST /v1/audio`) does not take it: each of its formats has its own rate. |
| `text` | string | yes | 1–2000 characters. |
| `stream` | boolean |  | Stream audio as it is generated. Only the pcm format can stream. Default `false`. |

**Responses**

| Status | Description |
|---|---|
| `200` | `audio/wav`, `audio/pcm` — The generated audio — a complete WAV, or a chunked `audio/pcm` stream when `stream` was set. Timing headers describe the generation |
| `400` | The request could not be read: malformed JSON |
| `401` | Missing or invalid credentials |
| `402` | Out of credits, or the organisation is suspended — nothing was charged |
| `403` | The key is valid but its scopes do not cover this capability — a key limited to `tts` gets this from `/v1/images` rather than a 401 |
| `404` | Unknown voice_id |
| `422` | The request failed validation |
| `429` | Rate limit exceeded |
| `502` | The provider failed; the message says why |
| `503` | Speech is not configured on this platform, or the voice could not be looked up — the message says which |