Skip to content

docs: note OpenAI's speech model shutdown dates and correct the STT model default #1485

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yoyoismee wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: note OpenAI's speech model shutdown dates and correct the STT model default #1485

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions docs/features/chat-conversations/audio/speech-to-text/openai-stt-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,14 @@ See the companion guide: [Using OpenAI for Text-to-Speech](/features/chat-conver
|-------|-------------|
| `gpt-transcribe` | Current OpenAI transcription model (recommended) — roughly half the word error rate of `whisper-1` |
| `gpt-live-transcribe` | Low-latency streaming transcription |
| `whisper-1` | Legacy Whisper large-v2 model, still available |
| `whisper-1` | Legacy Whisper large-v2 model, retiring on 2027-02-26 |

:::info
OpenAI recommends `gpt-transcribe` for new setups; `whisper-1` remains available and is what Open WebUI uses when `AUDIO_STT_MODEL` is unset. For fully local transcription, use Local Whisper (built into Open WebUI) or another provider such as Deepgram.
OpenAI recommends `gpt-transcribe` for new setups. `AUDIO_STT_MODEL` is empty by default, so set the model explicitly. For fully local transcription, use Local Whisper (built into Open WebUI) or another provider such as Deepgram.
:::

:::caution OpenAI is retiring older transcription models
OpenAI is removing `whisper-1`, `gpt-4o-transcribe`, `gpt-4o-mini-transcribe` and `gpt-4o-transcribe-diarize` from its API on 2027-02-26. If **STT Model** is set to one of them, switch to `gpt-transcribe` before then. See [OpenAI's deprecations page](https://developers.openai.com/api/docs/deprecations#2026-08-26-transcription-models) for details.
:::

## Environment Variables Setup
Expand All @@ -68,7 +72,7 @@ services:
| `AUDIO_STT_ENGINE` | Set to `openai` | empty (uses local Whisper) |
| `AUDIO_STT_OPENAI_API_BASE_URL` | OpenAI API base URL | `https://api.openai.com/v1` |
| `AUDIO_STT_OPENAI_API_KEY` | Your OpenAI API key | empty |
| `AUDIO_STT_MODEL` | STT model | `gpt-transcribe` |
| `AUDIO_STT_MODEL` | STT model | empty |
| `AUDIO_STT_SUPPORTED_CONTENT_TYPES` | Allowed audio MIME types | `audio/*,video/webm` |

### Supported Audio Formats
Expand Down Expand Up @@ -122,6 +126,7 @@ Choose **Local Whisper** if:
1. Check your OpenAI API key is valid
2. Verify the API Base URL is correct
3. Check container logs for error messages
4. If the API Base URL points to another OpenAI-compatible service, set **STT Model** to a model ID that service supports

### Language Issues

Expand Down
5 changes: 5 additions & 0 deletions docs/features/chat-conversations/audio/text-to-speech/openai-tts-integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,10 @@ See the companion guide: [Using OpenAI for Speech-to-Text](/features/chat-conver
| `tts-1` | Standard quality, lower latency | Real-time applications, faster responses |
| `tts-1-hd` | Higher quality audio | Pre-recorded content, premium audio quality |

:::caution OpenAI is retiring these models
OpenAI is removing `tts-1`, `tts-1-hd` and `gpt-4o-mini-tts` from its API on 2027-01-06. Its recommended replacement, `gpt-realtime-2.1-mini`, is not supported on the `/audio/speech` endpoint that the `OpenAI` engine calls, so changing the **TTS Model** is not enough. To keep using OpenAI for speech, switch to the [OpenAI Realtime engine](#using-the-openai-realtime-engine). See [OpenAI's deprecations page](https://developers.openai.com/api/docs/deprecations#2026-10-01-text-to-speech-models) for details.
:::

## Available Voices

OpenAI provides 6 built-in voices:
Expand Down Expand Up @@ -230,6 +234,7 @@ When reading long responses, Open WebUI can split text into chunks before sendin
1. Check your OpenAI API key is valid and has Audio API access
2. Verify the API Base URL is correct (`https://api.openai.com/v1`)
3. Check browser console (F12) for errors
4. If the API Base URL points to another OpenAI-compatible service, replace the default `tts-1` and `alloy` with a **TTS Model** and **TTS Voice** that service supports

### Audio Quality Issues

Expand Down