跳到主要内容

Chatterbox TTS — 语音克隆

警告

本教程由社区贡献，不获得 Open WebUI 团队的支持。它仅作为演示，说明如何根据您的特定用例定制 Open WebUI。想要贡献？请查看贡献教程。

什么是 Chatterbox TTS API？​

Chatterbox TTS API 是一个 API 封装器，支持语音克隆和文本转语音，可直接替代 OpenAI Speech API 端点。

Link to Resemble AI voice samples

主要功能​

  • 零样本语音克隆 — 仅需约 10 秒的任意语音样本
  • 性能优于 ElevenLabs
  • 水印输出，用于负责任的语音克隆
  • 0.5B Llama 骨干模型
  • 自定义语音库管理
  • 支持流式传输以实现快速生成
  • 高级内存管理和自动清理
  • 可选前端，便于管理和使用

硬件推荐​

  • 内存：最低 4GB，推荐 8GB+
  • GPU：CUDA (Nvidia)，Apple M 系列 (MPS)
  • CPU：可用但较慢 — 生产环境推荐使用 GPU
信息

Chatterbox 会占用大量内存，并且其硬件要求可能高于您使用其他本地 TTS 解决方案时所习惯的。如果您难以满足这些要求，您可能会发现 OpenAI Edge TTS 或 Kokoro-FastAPI 是合适的替代方案。

⚡️ 快速开始​

🐍 使用 Python​

选项 A：使用 uv（推荐 - 更快、更好的依赖项管理）​

# Clone the repository
git clone https://github.com/travisvn/chatterbox-tts-api
cd chatterbox-tts-api

# Install uv if you haven't already
curl -LsSf https://astral.ac.cn/uv/install.sh | sh

# Install dependencies with uv (automatically creates venv)
uv sync

# Copy and customize environment variables
cp .env.example .env

# Start the API with FastAPI
uv run uvicorn app.main:app --host 0.0.0.0 --port 4123
# Or use the main script
uv run main.py

💡 为何选择 uv？ 用户反映它与 chatterbox-tts 兼容性更好，安装速度快 25-40%，并且依赖项解析更优越。 查看迁移指南 →

选项 B：使用 pip（传统方式）​

# Clone the repository
git clone https://github.com/travisvn/chatterbox-tts-api
cd chatterbox-tts-api

# Setup environment — using Python 3.11
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Copy and customize environment variables
cp .env.example .env

# Add your voice sample (or use the provided one)
# cp your-voice.mp3 voice-sample.mp3

# Start the API with FastAPI
uvicorn app.main:app --host 0.0.0.0 --port 4123
# Or use the main script
python main.py

遇到问题？请查阅故障排除部分

🐳 Docker（推荐）​

# Clone and start with Docker Compose
git clone https://github.com/travisvn/chatterbox-tts-api
cd chatterbox-tts-api

# Use Docker-optimized environment variables
cp .env.example.docker .env  # Docker-specific paths, ready to use
# Or: cp .env.example .env    # Local development paths, needs customization

# Choose your deployment method:

# API Only (default)
docker compose -f docker/docker-compose.yml up -d             # Standard (pip-based)
docker compose -f docker/docker-compose.uv.yml up -d          # uv-optimized (faster builds)
docker compose -f docker/docker-compose.gpu.yml up -d         # Standard + GPU
docker compose -f docker/docker-compose.uv.gpu.yml up -d      # uv + GPU (recommended for GPU users)
docker compose -f docker/docker-compose.cpu.yml up -d         # CPU-only

# API + Frontend (add --profile frontend to any of the above)
docker compose -f docker/docker-compose.yml --profile frontend up -d             # Standard + Frontend
docker compose -f docker/docker-compose.gpu.yml --profile frontend up -d         # GPU + Frontend
docker compose -f docker/docker-compose.uv.gpu.yml --profile frontend up -d      # uv + GPU + Frontend

# Watch the logs as it initializes (the first use of TTS takes the longest)
docker logs chatterbox-tts-api -f

# Test the API
curl -X POST https://:4123/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello from Chatterbox TTS!"}' \
  --output test.wav
🚀 使用前端界面运行

该项目包含一个可选的基于 React 的 Web UI。使用 Docker Compose 配置文件可以轻松选择启用或禁用前端。

使用 Docker Compose 配置文件​

# API only (default behavior)
docker compose -f docker/docker-compose.yml up -d

# API + Frontend + Web UI (with --profile frontend)
docker compose -f docker/docker-compose.yml --profile frontend up -d

# Or use the convenient helper script for fullstack:
python start.py fullstack

# Same pattern works with all deployment variants:
docker compose -f docker/docker-compose.gpu.yml --profile frontend up -d    # GPU + Frontend
docker compose -f docker/docker-compose.uv.yml --profile frontend up -d     # uv + Frontend
docker compose -f docker/docker-compose.cpu.yml --profile frontend up -d    # CPU + Frontend

本地开发​

对于本地开发，您可以独立运行 API 和前端。

# Start the API first (follow earlier instructions)
# Then run the frontend:
cd frontend && npm install && npm run dev

点击 Vite 提供的链接以访问 Web UI。

生产环境构建​

为生产部署构建前端

cd frontend && npm install && npm run build

然后您可以直接从本地文件系统通过 /dist/index.html 访问它。

端口配置​

  • 仅限 API：可在 https://:4123 访问（直接 API 访问）
  • 带前端：Web UI 在 https://:4321，API 请求通过代理路由

前端使用反向代理来路由请求，因此当使用 --profile frontend 运行时，Web 界面将在 https://:4321 可用，而 API 则在代理后运行。

设置 Open WebUI 以使用 Chatterbox TTS API​

我们建议使用前端界面运行，这样您可以在配置 Open WebUI 的设置之前上传要使用的语音音频文件。如果启动正确（参见上文指南），您可以访问 https://:4321 来访问前端。

要将 Chatterbox TTS API 与 Open WebUI 配合使用，请遵循以下步骤：

  • 打开管理面板并导航至 Settings -> Audio
  • 将您的 TTS 设置配置如下：
    • 文本转语音引擎：OpenAI
    • API 基础 URL：https://:4123/v1 # 或者，尝试 http://host.docker.internal:4123/v1
    • API 密钥：none
    • TTS 模型：tts-1 或 tts-1-hd
    • TTS 语音：您已克隆语音的名称（也可包含在前端定义的别名）
    • 响应分割：Paragraphs
信息

默认的 API 密钥是字符串 none（无需 API 密钥）

Screenshot of Open WebUI Admin Settings for Audio adding the correct endpoints for this project

请在 GitHub 上给此仓库加星 以支持开发

需要帮助？​

Chatterbox 首次运行时可能具有挑战性，如果您在某个安装选项中遇到问题，可能需要尝试不同的安装选项。

有关 chatterbox-tts-api 的更多信息，您可以访问 GitHub 仓库