@@ -2,21 +2,50 @@
22summary: "Use Gradium text-to-speech in OpenClaw"
33read_when:
44 - You want Gradium for text-to-speech
5- - You need Gradium API key or voice configuration
5+ - You need Gradium API key, voice, or directive token configuration
66title: "Gradium"
77---
889-Gradium is a bundled text-to-speech provider for OpenClaw. It can generate normal audio replies, voice-note-compatible Opus output, and 8 kHz u-law audio for telephony surfaces.
9+[Gradium](https://gradium.ai) is a bundled text-to-speech provider for OpenClaw. The plugin can render normal audio replies (WAV), voice-note-compatible Opus output, and 8 kHz u-law audio for telephony surfaces.
10+11+| Property | Value |
12+| ------------- | ------------------------------------ |
13+| Provider id | `gradium` |
14+| Auth | `GRADIUM_API_KEY` or config `apiKey` |
15+| Base URL | `https://api.gradium.ai` (default) |
16+| Default voice | `Emma` (`YTpq7expH9539ERJ`) |
10171118## Setup
121913-Create a Gradium API key, then expose it to OpenClaw:
20+Create a Gradium API key, then expose it to OpenClaw with either an env var or the config key.
142115-```bash
16-export GRADIUM_API_KEY="gsk_..."
17-```
22+<Tabs>
23+<Tab title="Env var">
24+```bash
25+export GRADIUM_API_KEY="gsk_..."
26+```
27+</Tab>
28+29+<Tab title="Config key">
30+```json5
31+{
32+ messages: {
33+ tts: {
34+ auto: "always",
35+ provider: "gradium",
36+ providers: {
37+ gradium: {
38+ apiKey: "${GRADIUM_API_KEY}",
39+ },
40+ },
41+ },
42+ },
43+}
44+```
45+</Tab>
46+</Tabs>
184719-You can also store the key in config under `messages.tts.providers.gradium.apiKey`.
48+The plugin checks the resolved `apiKey` first and falls back to the `GRADIUM_API_KEY` environment variable.
20492150## Config
2251@@ -38,6 +67,14 @@ You can also store the key in config under `messages.tts.providers.gradium.apiKe
3867}
3968```
406970+| Key | Type | Description |
71+| ---------------------------------------- | ------ | --------------------------------------------------------------------------------------------- |
72+| `messages.tts.providers.gradium.apiKey` | string | Resolved API key. Supports `${ENV}` and secret refs. |
73+| `messages.tts.providers.gradium.baseUrl` | string | Override the API origin. Trailing slashes are stripped. Defaults to `https://api.gradium.ai`. |
74+| `messages.tts.providers.gradium.voiceId` | string | Default voice id used when no directive override is present. |
75+76+The output audio format is selected automatically by the runtime based on the target surface and is not configurable from `openclaw.json`. See [Output](#output) below.
77+4178## Voices
42794380| Name | Voice ID |
@@ -52,11 +89,33 @@ You can also store the key in config under `messages.tts.providers.gradium.apiKe
52895390Default voice: Emma.
549192+### Per-message voice override
93+94+When the active speech policy allows voice overrides, you can switch voices inline using a directive token. All of these resolve to the same `voiceId` override:
95+96+```text
97+/voice:LFZvm12tW_z0xfGo
98+/voice_id:LFZvm12tW_z0xfGo
99+/voiceid:LFZvm12tW_z0xfGo
100+/gradium_voice:LFZvm12tW_z0xfGo
101+/gradiumvoice:LFZvm12tW_z0xfGo
102+```
103+104+If the speech policy disables voice overrides, the directive is consumed but ignored.
105+55106## Output
5610757-- Audio-file replies use WAV.
58-- Voice-note replies use Opus and are marked voice-compatible.
59-- Telephony synthesis uses `ulaw_8000` at 8 kHz.
108+The runtime picks the output format from the target surface. The provider does not synthesize other formats today.
109+110+| Target | Format | File ext | Sample rate | Voice-compatible flag |
111+| -------------- | ----------- | -------- | ----------- | --------------------- |
112+| Standard audio | `wav` | `.wav` | provider | no |
113+| Voice note | `opus` | `.opus` | provider | yes |
114+| Telephony | `ulaw_8000` | n/a | 8 kHz | n/a |
115+116+## Auto-select order
117+118+Among configured TTS providers, Gradium's auto-select order is `30`. See [Text-to-Speech](/tools/tts) for how OpenClaw picks the active provider when `messages.tts.provider` is not pinned.
6011961120## Related
62121此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。