{"kind":"guides","slug":"text-to-speech-api-docker","path":"/guides/text-to-speech-api-docker","title":"在 Docker 中自建文字转语音 API | SuperClonica","description":"在 CPU 或 NVIDIA GPU 上用 Docker 运行自己的文字转语音 HTTP API：启动服务器、用自定义音色发送请求、设置 API 密钥并扩展。注意：Supertonic 3 不支持中文。","h1":"在 Docker 中自建文字转语音 API","intro":"重要提示：本文介绍的 Supertonic 3 模型和 SuperClonica 引擎不支持中文，可以朗读英语、日语、韩语、德语、俄语等 31 种语言。如果您需要中文语音，请选择其他模型。\n\n自己服务器上的文字转语音 API 可以为任何能发送 HTTP 请求的程序把文字变成音频：网站、机器人、游戏后端或任何语言的脚本。文字不会离开您的机器，也不按字符收费。本指南介绍如何在 Docker 中把基于开放模型 Supertonic 3 的 SuperClonica 引擎作为 HTTP 服务器运行：在 CPU 或 NVIDIA GPU 上启动、用内置音色和自定义音色发送请求，以及为实际使用做准备。镜像和引擎是我们的产品，涉及之处我们会说明。","sections":[{"heading":"为什么要自己运行语音合成","paragraphs":["云端语音 API 上手容易，但每次请求都会把文字发给服务商，并按字符计费。自建 API 则换成一台由您自己管理的服务器。"],"points":["隐私：文字和音频都留在您自己的硬件上，这对内部文档、消息和用户数据很重要。","成本：除了硬件之外，生成语音不再花钱；长文本和大批量也不会增加费用。","任何客户端：一个 HTTP 接口即可同样服务 Python、JavaScript、Go、PHP、C# 或 shell 脚本。","离线：模型下载一次后，服务器不再需要联网。"]},{"heading":"启动服务器","paragraphs":["在任意 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 会显示它何时就绪。"]},{"heading":"发送请求","paragraphs":["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 文档。"]},{"heading":"使用自定义音色","paragraphs":["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。"]},{"heading":"配置","paragraphs":["服务器从环境变量读取配置，可在 docker run 中用 -e 传入，或写在 Compose 文件里。"],"points":["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）。"]},{"heading":"投入生产之前","paragraphs":["几个习惯可以让自建语音 API 保持快速和安全。"],"points":["保留 /models 数据卷，这样重启时不必重新下载模型，并用 --restart unless-stopped 启动容器。","不要把 8000 端口原样暴露到互联网：请设置 API 密钥，并把服务器放在带 HTTPS 的反向代理之后，或只在私有网络中使用。","如果需要显示进度或流式输出，请自行把长文本拆成段落；引擎本身也会把长文本切成不超过 160 个字符的自然片段朗读。","对界面短语等重复出现的文本缓存音频：相同的文本、音色和 seed 总是生成同一个文件。","在自己的硬件上测试：在我们的测试中，短句在 RTX 5070 Ti 上耗时 0.12 秒，在 Ryzen 7 5800X 的四个线程上耗时 0.43 秒。"]},{"heading":"许可","paragraphs":["SuperClonica 引擎和镜像采用 Apache License 2.0 发布。Supertonic 3 模型采用 OpenRAIL-M 许可，这是一种免版税许可，列出了禁止用途，而不是禁止商用的条款：请勿在未经同意的情况下用语音冒充他人、欺骗或骚扰，并在必要时说明音频由机器生成。"]}],"faq":[{"question":"这个 API 兼容 OpenAI 的语音接口吗？","answer":"不兼容。它有自己简单的 JSON 格式：输入 text、voice、lang 和几个选项，输出 WAV 文件。在代码或代理中加一个小适配器即可转换其他格式。"},{"question":"需要 GPU 吗？","answer":"不需要。cpu 镜像可在普通处理器上运行，一句短句远不到一秒。NVIDIA GPU 配合 cuda 镜像要快好几倍，适合大批量处理。"},{"question":"它能同时处理多少个请求？","answer":"请求在 lane（模型副本）上处理；只有一个副本时，请求依次排队。设置 SUPERCLONICA_LANES（最多 8）即可同时处理多个请求；在 CPU 上各副本共享处理器核心，在 GPU 上则能更充分地利用显卡。"},{"question":"可以离线使用吗？","answer":"可以，首次启动之后即可。模型保存在 /models 数据卷中，此后服务器无需联网；只有拉取镜像和首次下载模型时需要互联网。注意它不支持中文。"}],"cta":{"catalog":"浏览适合 API 的音色","install":"引擎的其他安装方式"},"sources":[{"label":"SuperClonica Docker 镜像（Docker Hub）","url":"https://hub.docker.com/r/superclonica/superclonica"},{"label":"NVIDIA Container Toolkit 安装指南","url":"https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html"},{"label":"SuperClonica 引擎（PyPI）","url":"https://pypi.org/project/superclonica-cpu/"},{"label":"Supertonic 3 模型卡（Hugging Face）","url":"https://huggingface.co/supertone-oss-archive/supertonic-3"},{"label":"免费的 Supertonic 3 音色（GitHub）","url":"https://github.com/superclonica/supertonic-voices"}],"published":"2026-10-22","updated":"2026-10-22","pages":[{"slug":"offline-text-to-speech","path":"/guides/offline-text-to-speech","h1":"如何在自己的电脑上离线把文字转成语音"},{"slug":"voice-cloning","path":"/guides/voice-cloning","h1":"声音克隆：如何得到一个像录音里那样的声音"},{"slug":"best-free-tts-models","path":"/guides/best-free-tts-models","h1":"2026 年适合本地运行的免费语音合成模型"},{"slug":"text-to-speech-for-videos","path":"/guides/text-to-speech-for-videos","h1":"为视频、有声书、游戏和应用做文字转语音配音"},{"slug":"supertonic-3-voices","path":"/guides/supertonic-3-voices","h1":"Supertonic 3 音色：自定义音色的来源与使用方法"},{"slug":"python-text-to-speech","path":"/guides/python-text-to-speech","h1":"Python 文字转语音：离线、免费、自然的音色"},{"slug":"text-to-speech-api-docker","path":"/guides/text-to-speech-api-docker","h1":"在 Docker 中自建文字转语音 API"}],"related":[{"slug":"text-to-speech","path":"/text-to-speech","h1":"在自己电脑上运行的语音合成"},{"slug":"supertonic","path":"/compare/supertonic","h1":"Supertonic 与 SuperClonica：同一模型，更快更干净"},{"slug":"fish-audio","path":"/compare/fish-audio","h1":"Fish Audio、Fish Speech 与 SuperClonica 对比"},{"slug":"omnivoice","path":"/compare/omnivoice","h1":"OmniVoice 与 SuperClonica：语言更多，还是速度更快"},{"slug":"qwen3-tts","path":"/compare/qwen3-tts","h1":"本地语音合成：Qwen3-TTS 还是 SuperClonica"},{"slug":"voxcpm","path":"/compare/voxcpm","h1":"VoxCPM 2 与 SuperClonica：录音棚音质还是 CPU 速度"},{"slug":"f5-tts","path":"/compare/f5-tts","h1":"F5-TTS 与 SuperClonica：零样本克隆还是 CPU 上的快速合成"},{"slug":"elevenlabs","path":"/compare/elevenlabs","h1":"可离线使用的 ElevenLabs 替代方案"},{"slug":"kokoro","path":"/compare/kokoro","h1":"Kokoro TTS 与 SuperClonica：两个小模型的本地语音合成"},{"slug":"piper","path":"/compare/piper","h1":"Piper TTS 与 SuperClonica：小设备还是定制音色"},{"slug":"xtts","path":"/compare/xtts","h1":"Coqui XTTS-v2 与 SuperClonica：Coqui TTS 的替代方案"},{"slug":"chatterbox","path":"/compare/chatterbox","h1":"Chatterbox TTS 与 SuperClonica：即时克隆还是训练好的音色文件"}]}