
issue: Text-to-Speech broken after latest update when using local TTS provider via OpenAI engine
快速结论:该报错发生在 Open WebUI 更新后(例如 v0.6.27),当使用 OpenAI 引擎连接本地 TTS 端点(如 kokoro-fastapi)时,TTS 请求路径从预期的 /v1/audio/speech 错误地拼接为 /audio/speech,导致 404。优先排查 TTS API 基础 URL 末尾是否带 /v1,并验证 open_webui/routers/audio.py 中 urljoin 相对路径是否缺少斜杠处理。
问题场景
用户使用 Open WebUI(Docker 安装)并配置 Text-to-Speech 引擎为 OpenAI,API 基础 URL 指向本地 TTS 服务(例如 http://host.docker.internal:8880/v1),API key 设为 not-needed,选择本地 TTS 模型(例如 kokoro)。更新到最新版本后,点击“Read Aloud”按钮时触发此错误。
报错原文
External: 404, message='Not Found', url='http://host.docker.internal:8880/audio/speech'
POST /audio/speech HTTP/1.1" 404 Not Found
原因分析
可能原因:
1. Open WebUI 中的 urljoin 逻辑在拼接 TTS API URL 时,相对路径 /audio/speech(以斜杠开头)导致 urljoin 丢弃了基础 URL 中 /v1 之后的部分,最终请求被发送到 /audio/speech 而非正确的 /v1/audio/speech。
2. 此行为在 Pull Request #17061 或相关提交中引入,影响了 open_webui/routers/audio.py 第 342 行附近的代码。
环境排查
- 确认 Open WebUI 版本(如 v0.6.27 或更新版本)。
- 确认安装方式(Docker)。
- 确认 TTS 引擎配置:引擎为 OpenAI,API 基础 URL 是否包含
/v1路径(例如http://host.docker.internal:8880/v1)。 - 确认本地 TTS 服务(如 kokoro-fastapi)的日志是否显示
POST /audio/speech缺少/v1前缀。
解决步骤
- 本地修改代码(根据 Issue 中用户反馈的临时方案)
打开open_webui/routers/audio.py文件,找到urljoin调用所在行(约第 342 行)。
将相对路径的/audio/speech改为audio/speech(去除开头的斜杠):
修改前:
url=urljoin(request.app.state.config.TTS_OPENAI_API_BASE_URL, "/audio/speech")
修改后:
url=urljoin(request.app.state.config.TTS_OPENAI_API_BASE_URL, "audio/speech")
同时确保 TTS_OPENAI_API_BASE_URL 以斜杠结尾(例如http://host.docker.internal:8880/v1/),以配合urljoin正确处理路径。
可优先尝试:此方法已在 Issue 中被多位用户验证有效,但可能影响其他 TTS 配置。 - 配置层面尝试
在 Open WebUI 的 TTS 设置中,将 API 基础 URL 明确加上/v1后缀(如http://127.0.0.1:8004/v1),这已在版本 v0.9.6 中被部分用户报告为临时解决方案。 - 等待官方修复
注意:该 Issue 已关闭并包含相关的 revert 提交(8339f59cdfc63f2d58c8e26933d1bf1438479d75),建议更新到已包含此修复的最新版本。
验证方法
重新点击 TTS 功能中的“Read Aloud”按钮,检查是否不再弹出 404 错误。同时查看本地 TTS 服务日志(如 kokoro-fastapi),确认收到 POST /v1/audio/speech 请求且返回 200 OK。如果修改了代码,也建议确认其他使用 urljoin 的 TTS 功能未受影响。



