跳到主要内容

Chatterbox TTS：语音克隆

注意

本教程是社区贡献内容，不属于 OPL 数据空间官方支持范围。

什么是 Chatterbox TTS API​

Chatterbox TTS API 是一个兼容 OpenAI Speech API 的语音克隆与文本转语音服务封装。

它的特点包括：

  • 零样本语音克隆，只需要大约 10 秒声音样本
  • 水印输出，便于负责任地使用语音克隆
  • 自定义 Voice Library 管理
  • 支持流式输出
  • 带可选前端，方便管理和测试

硬件建议​

  • 内存：至少 4GB，推荐 8GB+
  • GPU：优先使用 CUDA（Nvidia）或 Apple M 系列（MPS）
  • CPU 也可运行，但更慢
信息

Chatterbox 对内存和硬件要求比很多本地 TTS 方案更高。如果你的机器条件有限，通常可以考虑 OpenAI Edge TTS 或 Kokoro-FastAPI。

快速开始​

Python 方式​

推荐使用 uv：

git clone https://github.com/travisvn/chatterbox-tts-api
cd chatterbox-tts-api
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
cp .env.example .env
uv run uvicorn app.main:app --host 0.0.0.0 --port 4123

也可以使用传统 pip + venv 方式。

Docker 方式（推荐）​

git clone https://github.com/travisvn/chatterbox-tts-api
cd chatterbox-tts-api
cp .env.example.docker .env
docker compose -f docker/docker-compose.yml up -d

常见变体：

  • docker-compose.gpu.yml
  • docker-compose.uv.yml
  • docker-compose.cpu.yml

如果要同时启用前端，可加 --profile frontend。

在 OPL 数据空间中配置​

建议先启用前端，这样你可以先上传声音样本，再回到 OPL 数据空间配置。

进入 管理员面板 → 设置 → 语音，设置：

  • Text-to-Speech Engine：OpenAI
  • API Base URL：http://localhost:4123/v1
    • 容器环境下也可尝试 host.docker.internal
  • API Key：none
  • TTS Model：tts-1 或 tts-1-hd
  • TTS Voice：你克隆后的声音名称
  • Response splitting：Paragraphs
信息

默认 API Key 是 none，即无需真实 API Key。

前端模式​

如果使用 --profile frontend，你会获得一个独立 Web UI：

  • 前端地址：http://localhost:4321
  • API 地址：http://localhost:4123

你可以用前端来管理克隆声音、别名和库内容。

故障排查​

内存要求​

Chatterbox 初次加载模型会比较慢，也可能吃掉较多内存。若容器频繁崩溃，优先检查：

  • 主机可用内存是否足够
  • GPU 显存是否够用
  • 是否误用了 CPU-only 模式来承载高负载语音生成

连接问题​

  • 确认 http://localhost:4123/v1 可达
  • Docker 中若 localhost 不通，改用 host.docker.internal
  • 先直接用 curl 测试 /v1/audio/speech

更多文档可见其 GitHub 仓库：