# 在 Docker 中自建文字转语音 API

更新于 2026-10-22

重要提示：本文介绍的 Supertonic 3 模型和 SuperClonica 引擎不支持中文，可以朗读英语、日语、韩语、德语、俄语等 31 种语言。如果您需要中文语音，请选择其他模型。

自己服务器上的文字转语音 API 可以为任何能发送 HTTP 请求的程序把文字变成音频：网站、机器人、游戏后端或任何语言的脚本。文字不会离开您的机器，也不按字符收费。本指南介绍如何在 Docker 中把基于开放模型 Supertonic 3 的 SuperClonica 引擎作为 HTTP 服务器运行：在 CPU 或 NVIDIA GPU 上启动、用内置音色和自定义音色发送请求，以及为实际使用做准备。镜像和引擎是我们的产品，涉及之处我们会说明。

## 为什么要自己运行语音合成

云端语音 API 上手容易，但每次请求都会把文字发给服务商，并按字符计费。自建 API 则换成一台由您自己管理的服务器。

- 隐私：文字和音频都留在您自己的硬件上，这对内部文档、消息和用户数据很重要。
- 成本：除了硬件之外，生成语音不再花钱；长文本和大批量也不会增加费用。
- 任何客户端：一个 HTTP 接口即可同样服务 Python、JavaScript、Go、PHP、C# 或 shell 脚本。
- 离线：模型下载一次后，服务器不再需要联网。

## 启动服务器

在任意 CPU 上：docker run -d --name tts -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cpu。在 NVIDIA GPU 上，先安装 NVIDIA Container Toolkit，再运行 docker run -d --name tts --gpus all -p 8000:8000 -v superclonica-models:/models superclonica/superclonica:cuda；镜像自带 CUDA 和 cuDNN，主机只需安装驱动。

首次启动时，约 385 MB 的 Supertonic 3 模型会下载到 superclonica-models 数据卷中，之后的启动会直接复用。当 GET http://localhost:8000/health 返回状态、版本和所用设备时，服务器就绪。镜像自带健康检查，因此 docker ps 会显示它何时就绪。

## 发送请求

POST /synthesize 接收 JSON 并返回 16 位单声道 WAV 文件：curl -X POST http://localhost:8000/synthesize -H "Content-Type: application/json" -d '{"text": "Hello from my own server!", "voice": "F1", "lang": "en"}' -o hello.wav。响应头 X-Sample-Rate 和 X-Duration-Seconds 描述音频信息。

字段包括 text、voice、lang、seed 和 normalize。voice 是 M1 至 M5、F1 至 F5 共十种内置音色之一，或自定义音色；lang 是文本语言，须为模型支持的 31 种语言之一（不包括中文）。固定 seed 可让同一文本再次得到相同音频，normalize 用于统一响度。GET /voices 列出内置音色和语言，/docs 提供交互式 API 文档。

## 使用自定义音色

Supertonic 3 的音色是一个约 0.3 MB 的 JSON 文件。带试听样本的免费音色放在 GitHub 的 superclonica/supertonic-voices 仓库中，SuperClonica 目录里还有 170 多种音色，每种都可以免费在线试听。

音色以 JSON 对象本身放进请求的 voice 字段，因此服务器不保存音色文件。由于对象较大，请把请求写进文件后用 curl -d @request.json 发送，或在代码中用 Python 的 json.load 或 JavaScript 的 JSON.parse 读取音色，再与文本一起发送。请求体最大 2 MB。

## 配置

服务器从环境变量读取配置，可在 docker run 中用 -e 传入，或写在 Compose 文件里。

- SUPERCLONICA_API_KEY：设置后，/synthesize 和 /voices 需要带有 Authorization: Bearer 和密钥的请求头。
- SUPERCLONICA_LANES：模型副本数，1 到 8（默认 1）；每个副本一次处理一个请求，并需要单独的内存。
- SUPERCLONICA_DEVICE：auto、cuda 或 cpu（默认 auto：有 GPU 时使用 GPU）。
- SUPERCLONICA_THREADS：CPU 线程数（默认每个物理核心一个）。
- SUPERCLONICA_MAX_TEXT：文本最大字符数（默认 5000）。

## 投入生产之前

几个习惯可以让自建语音 API 保持快速和安全。

- 保留 /models 数据卷，这样重启时不必重新下载模型，并用 --restart unless-stopped 启动容器。
- 不要把 8000 端口原样暴露到互联网：请设置 API 密钥，并把服务器放在带 HTTPS 的反向代理之后，或只在私有网络中使用。
- 如果需要显示进度或流式输出，请自行把长文本拆成段落；引擎本身也会把长文本切成不超过 160 个字符的自然片段朗读。
- 对界面短语等重复出现的文本缓存音频：相同的文本、音色和 seed 总是生成同一个文件。
- 在自己的硬件上测试：在我们的测试中，短句在 RTX 5070 Ti 上耗时 0.12 秒，在 Ryzen 7 5800X 的四个线程上耗时 0.43 秒。

## 许可

SuperClonica 引擎和镜像采用 Apache License 2.0 发布。Supertonic 3 模型采用 OpenRAIL-M 许可，这是一种免版税许可，列出了禁止用途，而不是禁止商用的条款：请勿在未经同意的情况下用语音冒充他人、欺骗或骚扰，并在必要时说明音频由机器生成。

## 更多指南

- [如何在自己的电脑上离线把文字转成语音](https://superclonica.com/zh/guides/offline-text-to-speech)
- [声音克隆：如何得到一个像录音里那样的声音](https://superclonica.com/zh/guides/voice-cloning)
- [2026 年适合本地运行的免费语音合成模型](https://superclonica.com/zh/guides/best-free-tts-models)
- [为视频、有声书、游戏和应用做文字转语音配音](https://superclonica.com/zh/guides/text-to-speech-for-videos)
- [Supertonic 3 音色：自定义音色的来源与使用方法](https://superclonica.com/zh/guides/supertonic-3-voices)
- [Python 文字转语音：离线、免费、自然的音色](https://superclonica.com/zh/guides/python-text-to-speech)

## 语音合成与对比

- [在自己电脑上运行的语音合成](https://superclonica.com/zh/text-to-speech)
- [Supertonic 与 SuperClonica：同一模型，更快更干净](https://superclonica.com/zh/compare/supertonic)
- [Fish Audio、Fish Speech 与 SuperClonica 对比](https://superclonica.com/zh/compare/fish-audio)
- [OmniVoice 与 SuperClonica：语言更多，还是速度更快](https://superclonica.com/zh/compare/omnivoice)
- [本地语音合成：Qwen3-TTS 还是 SuperClonica](https://superclonica.com/zh/compare/qwen3-tts)
- [VoxCPM 2 与 SuperClonica：录音棚音质还是 CPU 速度](https://superclonica.com/zh/compare/voxcpm)
- [F5-TTS 与 SuperClonica：零样本克隆还是 CPU 上的快速合成](https://superclonica.com/zh/compare/f5-tts)
- [可离线使用的 ElevenLabs 替代方案](https://superclonica.com/zh/compare/elevenlabs)
- [Kokoro TTS 与 SuperClonica：两个小模型的本地语音合成](https://superclonica.com/zh/compare/kokoro)
- [Piper TTS 与 SuperClonica：小设备还是定制音色](https://superclonica.com/zh/compare/piper)
- [Coqui XTTS-v2 与 SuperClonica：Coqui TTS 的替代方案](https://superclonica.com/zh/compare/xtts)
- [Chatterbox TTS 与 SuperClonica：即时克隆还是训练好的音色文件](https://superclonica.com/zh/compare/chatterbox)

## 常见问题

### 这个 API 兼容 OpenAI 的语音接口吗？

不兼容。它有自己简单的 JSON 格式：输入 text、voice、lang 和几个选项，输出 WAV 文件。在代码或代理中加一个小适配器即可转换其他格式。

### 需要 GPU 吗？

不需要。cpu 镜像可在普通处理器上运行，一句短句远不到一秒。NVIDIA GPU 配合 cuda 镜像要快好几倍，适合大批量处理。

### 它能同时处理多少个请求？

请求在 lane（模型副本）上处理；只有一个副本时，请求依次排队。设置 SUPERCLONICA_LANES（最多 8）即可同时处理多个请求；在 CPU 上各副本共享处理器核心，在 GPU 上则能更充分地利用显卡。

### 可以离线使用吗？

可以，首次启动之后即可。模型保存在 /models 数据卷中，此后服务器无需联网；只有拉取镜像和首次下载模型时需要互联网。注意它不支持中文。

- [浏览适合 API 的音色](https://superclonica.com/zh/explore)
- [引擎的其他安装方式](https://superclonica.com/zh/superclonica)

## 参考来源

- [SuperClonica Docker 镜像（Docker Hub）](https://hub.docker.com/r/superclonica/superclonica)
- [NVIDIA Container Toolkit 安装指南](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
- [SuperClonica 引擎（PyPI）](https://pypi.org/project/superclonica-cpu/)
- [Supertonic 3 模型卡（Hugging Face）](https://huggingface.co/supertone-oss-archive/supertonic-3)
- [免费的 Supertonic 3 音色（GitHub）](https://github.com/superclonica/supertonic-voices)
- [SuperClonica](https://superclonica.com/zh/)
- [文字转语音 AI 声音目录](https://superclonica.com/zh/explore)
- [Supertonic 3 定制音色委托](https://superclonica.com/zh/requests)
- [工作原理：音色、本地语音、训练](https://superclonica.com/zh/guide)
- [安装更快的 Supertonic 3 引擎](https://superclonica.com/zh/superclonica)
- [关于我们：语音合成爱好者团队](https://superclonica.com/zh/about)
- [联系方式、支持与音色投诉](https://superclonica.com/zh/contacts)
- [隐私政策](https://superclonica.com/zh/privacy)
- [使用条款](https://superclonica.com/zh/terms)
- [语音合成](https://superclonica.com/zh/text-to-speech)