> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Text to speech

> Generate speech on Gateway with POST /v1/audio/speech: raw audio bytes in the response, request fields, vendor-specific voices, and per-character billing.

`POST /v1/audio/speech` turns text into audio for narration, voice replies, or notifications. The response body is the raw audio, with no JSON wrapper; `Content-Type` names its format.

**`cURL`**

```bash title="cURL"
curl https://api-gateway.merge.dev/v1/audio/speech \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/tts-1", "input": "Your order has shipped and arrives Thursday.", "voice": "alloy"}' \
  -o speech.mp3
```

**`Python`**

```python title="Python"
import os, requests

resp = requests.post(
    "https://api-gateway.merge.dev/v1/audio/speech",
    headers={"Authorization": f"Bearer {os.environ['MERGE_GATEWAY_API_KEY']}"},
    json={"model": "openai/tts-1", "input": "Your order has shipped and arrives Thursday.", "voice": "alloy"},
)
with open("speech.mp3", "wb") as f:
    f.write(resp.content)
```

## Voices

| Model                                                             | Voices                                                                                                             | Output                               |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| `openai/tts-1`, `openai/tts-1-hd`                                 | OpenAI voices such as `alloy` and `nova`                                                                           | `response_format`, MP3 by default    |
| `google/gemini-3.8-flash-tts`, `google/gemini-3.8-flash-lite-tts` | Gemini voices such as `Kore` or `Puck`, or omit `voice`. OpenAI names fail with `No matching speaker voice found`. | WAV, whatever `response_format` says |
| `bland/bland-speech-v3`                                           | OpenAI voice names, mapped to Bland voices, or a Bland voice UUID                                                  | WAV                                  |
| Other vendors, such as `minimax/speech-2.6-turbo`                 | The vendor's own voice IDs                                                                                         | Vendor-specific                      |

The Gemini TTS models run on the `google` vendor only and take up to 8,192 input tokens.

## Reference

| Field             | Notes                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------- |
| `model`           | Required. A canonical model ID, since `@alias/...` returns `400 alias_not_supported`. |
| `input`           | Required. The text to speak.                                                          |
| `voice`           | Model-specific, see above                                                             |
| `response_format` | `mp3`, `opus`, `aac`, `flac`, `wav`, or `pcm`                                         |
| `speed`           | 0.25 to 4.0                                                                           |
| `instructions`    | Voice direction, on models that support it                                            |
| `vendor`          | Pin the execution vendor                                                              |
| `customer`        | Customer UUID to scope the key, budget, and usage to                                  |

Other fields are forwarded to the vendor. Speech bills per input character (`unit: per_character` on `GET /v1/models`). `X-Merge-Billed-Characters` gives the count billed after any [DLP](/merge-gateway/security/data-loss-prevention) redaction, and `X-Merge-Vendor` names the vendor.

## Next steps

#### [Speech to text](/merge-gateway/capabilities/multimodal/speech-to-text)

Transcribe an audio file

#### [Live voice](/merge-gateway/capabilities/multimodal/live-voice)

Full-duplex voice sessions over a WebSocket