From 927bb389da8a68999866de60558a51f3eca71899 Mon Sep 17 00:00:00 2001 From: sam Date: Mon, 24 Aug 2026 13:19:21 -0700 Subject: [PATCH 1/2] Add Gandr TTS integration guide --- .../text-to-speech/gandr-tts-integration.md | 128 ++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 docs/features/chat-conversations/audio/text-to-speech/gandr-tts-integration.md diff --git a/docs/features/chat-conversations/audio/text-to-speech/gandr-tts-integration.md b/docs/features/chat-conversations/audio/text-to-speech/gandr-tts-integration.md new file mode 100644 index 000000000..8a071290c --- /dev/null +++ b/docs/features/chat-conversations/audio/text-to-speech/gandr-tts-integration.md @@ -0,0 +1,128 @@ +--- +sidebar_position: 4 +title: "Gandr TTS Integration" +--- + +# Using Gandr for Text-to-Speech + +:::warning + +This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the contributing tutorial. + +::: + +This guide covers how to use [Gandr](https://gandr.ai) as the Text-to-Speech engine in Open WebUI. Gandr serves an OpenAI-compatible Audio API, so Open WebUI's built-in `OpenAI` engine connects to it with no extra components to run. + +## What is Gandr? + +Gandr is a hosted text-to-speech API: + +- OpenAI-compatible `POST /v1/audio/speech` endpoint, responses in `mp3` by default (`wav` and `pcm` also supported) +- 23 languages +- Six stock voices, plus voice cloning from roughly ten seconds of reference audio through the API +- A streaming WebSocket endpoint for realtime agents ([docs](https://gandr.ai/docs)) +- Free tier: 50,000 tokens to start. One token is one character. + +## Requirements + +- A Gandr API key. Create one at [gandr.ai](https://gandr.ai); the free tier covers your first 50,000 tokens. +- Open WebUI installed and running + +## Quick Setup (UI) + +1. Click your **profile icon** (bottom-left corner) +2. Select **Admin Panel** +3. Click **Settings** → **Audio** tab → **Text-to-Speech Settings** +4. Configure the following: + +| Setting | Value | +|---------|-------| +| **Text-to-Speech Engine** | `OpenAI` | +| **API Base URL** | `https://tts.gandr.ai/v1` | +| **API Key** | Your Gandr API key (`gnd_...`) | +| **TTS Model** | `gandr` | +| **TTS Voice** | `gandr-mia` | + +5. Click **Save** + +:::tip + +Gandr returns `mp3` by default, which Open WebUI plays natively. Unlike some providers, you do not need to add anything to the **OpenAI Params** field. + +::: + +## Available Voices + +Six stock voices are available out of the box: + +| Voice ID | +|----------| +| `gandr-mia` | +| `gandr-ava` | +| `gandr-jenny` | +| `gandr-dane` | +| `gandr-leo` | +| `gandr-lewis` | + +Set any of these as the **TTS Voice** in the settings above, or per model in the Model Editor, or per user in user settings. You can hear samples of each voice at [gandr.ai](https://gandr.ai). + +## Language + +Open WebUI sends the text and Gandr detects the language. To pin a language explicitly (for example `en`, `es`, `fr`, `de`, `pt`, `ar`, `zh`, `ja`), use the streaming WebSocket API described at [gandr.ai/docs](https://gandr.ai/docs); the OpenAI-compatible endpoint above needs no language configuration. + +## Environment Variables Setup + +If you prefer to configure via environment variables: + +```yaml +services: + open-webui: + image: ghcr.io/open-webui/open-webui:main + environment: + - AUDIO_TTS_ENGINE=openai + - AUDIO_TTS_OPENAI_API_BASE_URL=https://tts.gandr.ai/v1 + - AUDIO_TTS_OPENAI_API_KEY=gnd_... + - AUDIO_TTS_MODEL=gandr + - AUDIO_TTS_VOICE=gandr-mia + # ... other configuration +``` + +### All TTS Environment Variables + +| Variable | Description | Default | +|----------|-------------|---------| +| `AUDIO_TTS_ENGINE` | Set to `openai` | empty | +| `AUDIO_TTS_OPENAI_API_BASE_URL` | Gandr base URL | `https://api.openai.com/v1` | +| `AUDIO_TTS_OPENAI_API_KEY` | Your Gandr API key | empty | +| `AUDIO_TTS_MODEL` | Any value; `gandr` is conventional | engine default | +| `AUDIO_TTS_VOICE` | A Gandr voice ID, e.g. `gandr-mia` | `alloy` | + +## Testing TTS + +1. Start a new chat +2. Send a message to any model +3. Click the **speaker icon** on the AI response to hear it read aloud + +## Troubleshooting + +### 401 Unauthorized + +The API key is missing or malformed. Gandr keys start with `gnd_`. Generate a fresh key at [gandr.ai](https://gandr.ai) and paste it again. + +### No Audio Plays + +1. Verify the API Base URL is exactly `https://tts.gandr.ai/v1` +2. Check the browser console (F12) for errors +3. Test the key outside Open WebUI: + +```bash +curl -X POST https://tts.gandr.ai/v1/audio/speech \ + -H "Authorization: Bearer gnd_YOUR_KEY" \ + -H "Content-Type: application/json" \ + -d '{"model": "gandr", "input": "Hello from Gandr.", "voice": "gandr-mia"}' \ + --output test.mp3 +``` + +### Out of Tokens + +Each character of text is one token. Top up or check usage from your account at [gandr.ai](https://gandr.ai). From 3e4a4157181e5d2ad1b7001b0bff4bcc8c65a785 Mon Sep 17 00:00:00 2001 From: Sam Alghaithi Date: Fri, 28 Aug 2026 23:54:54 -0700 Subject: [PATCH 2/2] Correct the language note: the OpenAI-compatible route renders English --- .../audio/text-to-speech/gandr-tts-integration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/chat-conversations/audio/text-to-speech/gandr-tts-integration.md b/docs/features/chat-conversations/audio/text-to-speech/gandr-tts-integration.md index 8a071290c..215276316 100644 --- a/docs/features/chat-conversations/audio/text-to-speech/gandr-tts-integration.md +++ b/docs/features/chat-conversations/audio/text-to-speech/gandr-tts-integration.md @@ -68,7 +68,7 @@ Set any of these as the **TTS Voice** in the settings above, or per model in the ## Language -Open WebUI sends the text and Gandr detects the language. To pin a language explicitly (for example `en`, `es`, `fr`, `de`, `pt`, `ar`, `zh`, `ja`), use the streaming WebSocket API described at [gandr.ai/docs](https://gandr.ai/docs); the OpenAI-compatible endpoint above needs no language configuration. +Open WebUI sends the text and this route renders it in English; for the other languages, use Gandr's WebSocket API, which takes an explicit language parameter. To pin a language explicitly (for example `en`, `es`, `fr`, `de`, `pt`, `ar`, `zh`, `ja`), use the streaming WebSocket API described at [gandr.ai/docs](https://gandr.ai/docs); the OpenAI-compatible endpoint above needs no language configuration. ## Environment Variables Setup