title: "Text-to-speech"

---

OpenClaw can convert outbound replies into audio using ElevenLabs, Google Gemini, Microsoft, MiniMax, OpenAI, or xAI.

OpenClaw can convert outbound replies into audio using ElevenLabs, Google Gemini, Gradium, Microsoft, MiniMax, OpenAI, Vydra, or xAI.

It works anywhere OpenClaw can send audio.

## Supported services

- **ElevenLabs** (primary or fallback provider)

- **Google Gemini** (primary or fallback provider; uses Gemini API TTS)

- **Gradium** (primary or fallback provider; supports voice-note and telephony output)

- **Microsoft** (primary or fallback provider; current bundled implementation uses `node-edge-tts`)

- **MiniMax** (primary or fallback provider; uses the T2A v2 API)

- **OpenAI** (primary or fallback provider; also used for summaries)

- **Vydra** (primary or fallback provider; shared image, video, and speech provider)

- **xAI** (primary or fallback provider; uses the xAI TTS API)

### Microsoft speech notes

## Optional keys

If you want OpenAI, ElevenLabs, Google Gemini, MiniMax, or xAI:

If you want OpenAI, ElevenLabs, Google Gemini, Gradium, MiniMax, Vydra, or xAI:

- `ELEVENLABS_API_KEY` (or `XI_API_KEY`)

- `GEMINI_API_KEY` (or `GOOGLE_API_KEY`)

- `GRADIUM_API_KEY`

- `MINIMAX_API_KEY`

- `OPENAI_API_KEY`

- `VYDRA_API_KEY`

- `XAI_API_KEY`

Microsoft speech does **not** require an API key.

- [OpenAI Audio API reference](https://platform.openai.com/docs/api-reference/audio)

- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech)

- [ElevenLabs Authentication](https://elevenlabs.io/docs/api-reference/authentication)

- [Gradium](/providers/gradium)

- [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2)

- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)

- [Microsoft Speech output formats](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)

Current live voices are `ara`, `eve`, `leo`, `rex`, `sal`, and `una`; `eve` is

the default. `language` accepts a BCP-47 tag or `auto`.

### Gradium primary

```json5

{

messages: {

tts: {

auto: "always",

provider: "gradium",

providers: {

gradium: {

apiKey: "gradium_api_key",

baseUrl: "https://api.gradium.ai",

voiceId: "YTpq7expH9539ERJ",

},

},

},

},

}

```

### Disable Microsoft speech

```json5

- `tagged` only sends audio when the reply includes `[[tts:key=value]]` directives or a `[[tts:text]]...[[/tts:text]]` block.

- `enabled`: legacy toggle (doctor migrates this to `auto`).

- `mode`: `"final"` (default) or `"all"` (includes tool/block replies).

- `provider`: speech provider id such as `"elevenlabs"`, `"google"`, `"microsoft"`, `"minimax"`, or `"openai"` (fallback is automatic).

- `provider`: speech provider id such as `"elevenlabs"`, `"google"`, `"gradium"`, `"microsoft"`, `"minimax"`, `"openai"`, `"vydra"`, or `"xai"` (fallback is automatic).

- If `provider` is **unset**, OpenClaw uses the first configured speech provider in registry auto-select order.

- Legacy `provider: "edge"` still works and is normalized to `microsoft`.

- `summaryModel`: optional cheap model for auto-summary; defaults to `agents.defaults.model.primary`.

- `maxTextLength`: hard cap for TTS input (chars). `/tts audio` fails if exceeded.

- `timeoutMs`: request timeout (ms).

- `prefsPath`: override the local prefs JSON path (provider/limit/summary).

- `apiKey` values fall back to env vars (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`).

- `apiKey` values fall back to env vars (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `GRADIUM_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`, `VYDRA_API_KEY`, `XAI_API_KEY`).

- `providers.elevenlabs.baseUrl`: override ElevenLabs API base URL.

- `providers.openai.baseUrl`: override the OpenAI TTS endpoint.

- Resolution order: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1`

- `providers.google.voiceName`: Gemini prebuilt voice name (default `Kore`; `voice` is also accepted).

- `providers.google.baseUrl`: override the Gemini API base URL. Only `https://generativelanguage.googleapis.com` is accepted.

- If `messages.tts.providers.google.apiKey` is omitted, TTS can reuse `models.providers.google.apiKey` before env fallback.

- `providers.gradium.baseUrl`: override Gradium API base URL (default `https://api.gradium.ai`).

- `providers.gradium.voiceId`: Gradium voice identifier (default Emma, `YTpq7expH9539ERJ`).

- `providers.xai.apiKey`: xAI TTS API key (env: `XAI_API_KEY`).

- `providers.xai.baseUrl`: override the xAI TTS base URL (default `https://api.x.ai/v1`, env: `XAI_BASE_URL`).

- `providers.xai.voiceId`: xAI voice id (default `eve`; current live voices: `ara`, `eve`, `leo`, `rex`, `sal`, `una`).

Available directive keys (when enabled):

- `provider` (registered speech provider id, for example `openai`, `elevenlabs`, `google`, `minimax`, or `microsoft`; requires `allowProvider: true`)

- `voice` (OpenAI voice), `voiceName` / `voice_name` / `google_voice` (Google voice), or `voiceId` (ElevenLabs / MiniMax / xAI)

- `provider` (registered speech provider id, for example `openai`, `elevenlabs`, `google`, `gradium`, `minimax`, `microsoft`, `vydra`, or `xai`; requires `allowProvider: true`)

- `voice` (OpenAI or Gradium voice), `voiceName` / `voice_name` / `google_voice` (Google voice), or `voiceId` (ElevenLabs / Gradium / MiniMax / xAI)

- `model` (OpenAI TTS model, ElevenLabs model id, or MiniMax model) or `google_model` (Google TTS model)

- `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost`

- `vol` / `volume` (MiniMax volume, 0-10)

- 44.1kHz / 128kbps is the default balance for speech clarity.

- **MiniMax**: MP3 (`speech-2.8-hd` model, 32kHz sample rate). Voice-note format not natively supported; use OpenAI or ElevenLabs for guaranteed Opus voice messages.

- **Google Gemini**: Gemini API TTS returns raw 24kHz PCM. OpenClaw wraps it as WAV for audio attachments and returns PCM directly for Talk/telephony. Native Opus voice-note format is not supported by this path.

- **Gradium**: WAV for audio attachments, Opus for voice-note targets, and `ulaw_8000` at 8 kHz for telephony.

- **xAI**: MP3 by default; `responseFormat` may be `mp3`, `wav`, `pcm`, `mulaw`, or `alaw`. OpenClaw uses xAI's batch REST TTS endpoint and returns a complete audio attachment; xAI's streaming TTS WebSocket is not used by this provider path. Native Opus voice-note format is not supported by this path.

- **Microsoft**: uses `microsoft.outputFormat` (default `audio-24khz-48kbitrate-mono-mp3`).

- The bundled transport accepts an `outputFormat`, but not all formats are available from the service.