OpenAI-Compatible Edge-TTS API 完整文档

以下是基于仓库内容的完整文档，包括使用相关内容和安装教程。文档聚焦于 API 的功能、请求方式、参数配置、集成示例，以及完整的安装指导（包括先决条件、步骤、环境变量和运行选项）。所有内容已翻译并整理为中文，便于阅读。

特点（Features）

兼容 OpenAI 的端点：使用 /v1/audio/speech，请求结构和行为与 OpenAI TTS 类似。
SSE 流支持：指定 stream_format: "sse" 时，通过服务器发送事件（SSE）实现实时音频流。
支持的语音：将 OpenAI 语音（alloy、echo、fable、onyx、nova、shimmer）映射到 edge-tts 等效语音。
灵活的格式：支持多种音频格式（mp3、opus、aac、flac、wav、pcm）。
可调速度：可修改播放速度（0.25x 到 4.0x）。
可选的 Direct Edge-TTS 语音选择：可以使用 OpenAI 语音映射，或直接指定任何 edge-tts 语音。

用法（Usage）

该 API 模拟 OpenAI 的 TTS 端点，允许用户通过文本生成语音，支持多种语音选项、格式和速度。服务器运行后，可通过 http://localhost:5050（或替换为本地 IP，如 192.168.0.1）访问。

端点：/v1/audio/speech
请求结构：类似于 OpenAI TTS API 的 POST 请求。
- 必需参数：
  - model：TTS 模型（默认兼容 edge-tts，例如 tts-1 或 tts-1-hd）。
  - input：要转换的文本。
  - voice：语音选项（OpenAI 映射或直接 edge-tts 语音，如 alloy、echo、fable、onyx、nova、shimmer）。
- 可选参数：
  - response_format：音频格式（默认 mp3）。
  - speed：播放速度（默认 1.0）。
  - stream_format：设置为 “sse” 以启用实时流。
API 密钥：使用自定义字符串作为 API_KEY（无需真实 OpenAI 密钥）。
其他扩展：
- 支持 Markdown 过滤（可禁用）。
- 详细错误日志（可选启用）。
- 语言默认 en-US，可自定义。

示例用例（Example Use Case）

提示：如果从其他设备或来源（如 Open WebUI）访问端点，可能需将 localhost 替换为本地 IP（例如 192.168.0.1）。
基本请求示例（假设服务器运行中）：
- 使用 curl 或类似工具发送 POST 请求到 /v1/audio/speech，包含文本、语音和格式。
- 示例：生成英语文本的 mp3 音频，使用默认速度。

集成示例

Open WebUI 集成

Open WebUI 支持多种 TTS 提供商，包括 OpenAI-compatible endpoints（如本 Edge-TTS API）、Azure Speech Services、ElevenLabs（支持 EU 驻留）、本地 Transformers 模型，以及浏览器-based WebAPI。TTS 用于读取 LLM 响应，支持自定义消息内容分段以生成 TTS 请求，提供灵活的语音输出选项。

配置步骤：
1. 打开 Open WebUI 的 Admin Panel > Settings > Audio（音频设置）。
2. 选择 TTS Engine 为 OpenAI（或 OpenAI-compatible）。
3. 设置 API Base URL：http://localhost:5050/v1（如果在 Docker 中运行，使用 http://host.docker.internal:5050/v1 以确保容器间通信）。
4. 输入 API Key：使用自定义密钥（如 your_api_key_here）。
5. TTS Model：推荐 tts-1 或 tts-1-hd（高清版本，使用 OpenAI 样本作为默认）。
6. TTS Voice：选择支持的语音，如 alloy、echo、fable、onyx、nova、shimmer（这些会映射到 Edge-TTS 等效语音）。
7. 保存设置并刷新页面以应用更改。
支持的语音和模型：
- OpenAI-compatible 语音：alloy（柔和中性）、echo（回声风格）、echo-alt（备选回声）、fable（故事讲述）、onyx（宝石般清晰）、nova（新星般明亮）、shimmer（闪烁效果）。
- 其他兼容模型：如 Piper TTS（CPU 快速运行，支持自定义语音通过 voice_to_speaker.yaml）、Parler-TTS（实验性，支持基于描述生成语音，如 “warm, natural English voice”）。
额外功能：
- 支持实验性 SpeechT5 TTS（本地支持，提升 TTS 能力）。
- 与 STT（Speech-to-Text）结合，实现免提语音/视频通话。STT 支持本地 Whisper、OpenAI、Deepgram、Azure 等。
- 自定义 TTS 分段：控制消息内容如何分段发送到 TTS 生成请求，提供灵活输出。
- 提示：浏览器安全措施要求 STT/TTS 在 HTTPS 下运行；如果使用 HTTP，可能需配置代理或启用 HTTPS 以避免功能限制。
与其他 TTS 工具的类似集成：
- 如 Kokoro Web：TTS Model 为 model_q8f16（大小/质量平衡），Voice 为 af_heart（默认温暖自然英语语音）。
- Chatterbox TTS：支持语音克隆，需上传音频文件到前端界面（例如 http://localhost:4321），然后配置 Open WebUI 设置。适用于更高硬件需求的环境。
- openedai-speech：支持多种模型，包括 Piper TTS、Parler-TTS，支持基本语音描述生成。
参考官方 Open WebUI 文档：查看 https://docs.openwebui.com/features/audio/text-to-speech/ 以获取更多 TTS 集成细节，包括特定提供商的教程。

AnythingLLM 集成

从版本 1.6.8 开始，支持通用 OpenAI TTS 提供商。
打开 Settings > Voice & Speech（在 AI Providers 下）。
配置 TTS Provider 为 OpenAI-compatible。
API 端点 URL：http://localhost:5050/v1。
输入自定义 API 密钥。

语音样本（Voice Samples）

支持播放语音样本，并查看所有可用 Edge TTS 语音。
OpenAI 语音映射：alloy、echo、fable、onyx、nova、shimmer 对应特定 edge-tts 语音。
默认语音：en-US-AvaNeural。

快速信息（Quick Info）

your_api_key_here 无需替换，使用任意字符串作为密钥。
该 API 免费，使用 Microsoft Edge 的在线 TTS 服务。
适用于个人使用；企业或非个人用途需联系 tts@travisvn.com。

关于（About）

免费、高质量的文本转语音 API 端点，可替代 OpenAI、Azure 或 ElevenLabs。基于 edge-tts，提供自托管选项，支持 AI 应用如 GPT、Claude、LLM 等。特别适用于与 Open WebUI 等平台的集成，实现自然语音交互。

许可证（License）

采用 GNU General Public License v3.0 (GPL-3.0)，适用于个人使用。

安装教程（Installation Guide）

以下是完整的安装说明，包括先决条件、快速启动和详细步骤。推荐使用 Docker 以简化部署。该项目利用 edge-tts 提供免费的在线 TTS 服务，无需额外费用。

先决条件（Prerequisites）

Docker（推荐）：用于容器化设置，包括 Docker 和 Docker Compose。
Python（可选）：用于本地开发，在 requirements.txt 中安装依赖。
ffmpeg（可选）：用于音频格式转换。如果仅使用 mp3 格式，则无需安装。

⚡️ 快速启动（Quick Start）

无需任何配置的最简单方法是运行以下命令（需要 Docker）：

docker run -d -p 5050:5050 travisvn/openai-edge-tts:latest

这将在 5050 端口运行服务，使用所有默认配置。服务将可在 http://localhost:5050 访问。

详细安装步骤（Detailed Installation）

克隆仓库（Clone the Repository）：

git clone https://github.com/travisvn/openai-edge-tts.git
cd openai-edge-tts

环境变量配置（Environment Variables）：
在根目录创建一个 .env 文件，包含以下变量：
```
API_KEY=your_api_key_here
PORT=5050

DEFAULT_VOICE=en-US-AvaNeural
DEFAULT_RESPONSE_FORMAT=mp3
DEFAULT_SPEED=1.0

DEFAULT_LANGUAGE=en-US

REQUIRE_API_KEY=True
REMOVE_FILTER=False
EXPAND_API=True
DETAILED_ERROR_LOGGING=True
```
或者，复制默认的 .env.example：
```
cp .env.example .env
```
- 说明：
  - API_KEY：自定义字符串（无需真实密钥）。
  - PORT：服务端口（默认 5050）。
  - DEFAULT_VOICE：默认语音（en-US-AvaNeural）。
  - DEFAULT_RESPONSE_FORMAT：默认音频格式（mp3）。
  - DEFAULT_SPEED：默认速度（1.0）。
  - DEFAULT_LANGUAGE：默认语言（en-US）。
  - REQUIRE_API_KEY：是否要求 API 密钥（True/False）。
  - REMOVE_FILTER：是否禁用 Markdown 过滤（False）。
  - EXPAND_API：是否扩展 API 支持（True）。
  - DETAILED_ERROR_LOGGING：是否启用详细错误日志（True）。
使用 Docker Compose 运行（推荐）（Run with Docker Compose）：
```
docker compose up --build
```
- 要后台运行，使用 -d 标志：
```
docker compose up -d
```
- 带 FFmpeg 的本地构建：Docker Compose 会自动安装 FFmpeg 以支持格式转换。

直接使用 Docker 运行（Run Directly with Docker）：

docker build -t openai-edge-tts .
docker run -p 5050:5050 --env-file .env openai-edge-tts

后台运行：

docker run -d -p 5050:5050 --env-file .env openai-edge-tts

快速 Docker 命令（无克隆）：

docker run -d -p 5050:5050 -e API_KEY=your_api_key_here -e PORT=5050 travisvn/openai-edge-tts:latest

使用 Python 运行（Running with Python）：
- 安装依赖：
```
pip install -r requirements.txt
```
- 运行服务器（使用环境变量）：
```
python app.py
```
- 说明：适用于本地开发，但推荐 Docker 以避免依赖问题。FFmpeg 需手动安装以支持非 mp3 格式。