You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Browse filesBrowse the repository at this point in the historyBrowse files
bunnysayzz
committed
docs: document OpenRouter TTS integration and response_format requirement
Closesopen-webui/open-webui#28143
Adds a dedicated section to the OpenAI TTS Integration guide covering:
- Configuring OpenRouter as a TTS provider via the OpenAI-compatible engine
- The AUDIO_TTS_OPENAI_PARAMS env var for docker-compose setups
- Why response_format must be set to mp3 (OpenRouter defaults to pcm,
which Open WebUI cannot play back, causing a 400 Bad Request)
Copy file name to clipboardExpand all lines: docs/features/chat-conversations/audio/text-to-speech/openai-tts-integration.md
+56Lines changed: 56 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -112,6 +112,62 @@ services:
112
112
|`AUDIO_TTS_MODEL`| TTS model (`tts-1` or `tts-1-hd`) |`tts-1`|
113
113
|`AUDIO_TTS_VOICE`| Voice to use |`alloy`|
114
114
115
+
## Using OpenRouter as a Text-to-Speech Provider
116
+
117
+
Open WebUI's `OpenAI` TTS engine is compatible with any service that implements the OpenAI Audio API, including [OpenRouter](https://openrouter.ai). This section explains how to configure OpenRouter as your TTS provider and how to avoid a common `400 Bad Request` error.
118
+
119
+
### Why the 400 Error Happens
120
+
121
+
OpenRouter's [`/audio/speech` endpoint](https://openrouter.ai/docs/guides/overview/multimodal/tts) defaults `response_format` to `pcm` when the field is omitted. Open WebUI does not send `response_format` in its request payload, so OpenRouter returns raw PCM audio, which Open WebUI cannot play back — resulting in a `400 Bad Request`.
122
+
123
+
The fix is to explicitly request MP3 by adding `{"response_format": "mp3"}` to the **OpenAI Params** field (extra parameters) in the TTS settings.
124
+
125
+
### Quick Setup (UI)
126
+
127
+
1. Click your **profile icon** (bottom-left corner)
|**API Key**| Your OpenRouter API key (`sk-or-...`) |
137
+
|**TTS Model**| Any OpenRouter TTS model, e.g. `openai/tts-1`|
138
+
|**TTS Voice**| Choose from available voices |
139
+
|**OpenAI Params**|`{"response_format": "mp3"}`|
140
+
141
+
:::important
142
+
143
+
The **OpenAI Params** field must contain `{"response_format": "mp3"}`. Without it, OpenRouter defaults to `pcm`, and speech requests fail with a `400 Bad Request` error.
144
+
:::
145
+
146
+
5. Click **Save**
147
+
148
+
### Environment Variables Setup
149
+
150
+
If you prefer to configure via environment variables, add the parameters JSON via `AUDIO_TTS_OPENAI_PARAMS`:
OpenRouter supports `mp3` and `pcm` output formats. Always select `mp3` in Open WebUI — PCM output is intended for real-time streaming pipelines and cannot be played back by Open WebUI.
0 commit comments