指南

在 Docker 中自建文字转语音 API

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

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

浏览适合 API 的音色 引擎的其他安装方式

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

云端语音 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 许可，这是一种免版税许可，列出了禁止用途，而不是禁止商用的条款：请勿在未经同意的情况下用语音冒充他人、欺骗或骚扰，并在必要时说明音频由机器生成。