5 分钟跑通本地语音合成ChatTTS-UI 部署与文字转语音 API 实战【免费下载链接】ChatTTS-ui一个简单的本地网页界面使用ChatTTS将文字合成为语音同时支持对外提供API接口。A simple native web interface that uses ChatTTS to synthesize text into speech, along with support for external API interfaces.项目地址: https://gitcode.com/GitHub_Trending/ch/ChatTTS-ui你是否有过这样的经历想给短视频配上旁白、给自家 App 加上语音播报结果被一堆“环境配置”劝退——Python 版本不对、依赖装不上、模型下载失败折腾一晚上还是只听到自己的键盘声。今天要聊的 ChatTTS-UI就是一个把本地语音合成这件事拉回“5 分钟能跑通”的工具它自带网页界面支持中英文混合、数字和符号的文字转语音合成还对外提供 REST API 接口你甚至不用写一行前端代码就能拥有一台属于自己的语音合成服务。我会按“5 分钟跑通 → 按需调优 → 进阶集成”三步走每读一小节你都能获得一个可落地的收获。全程命令可直接复制开箱即用。第一节先认识它——ChatTTS-UI 到底帮你解决了什么市面上很多文字转语音工具要么是线上服务要花钱、传数据不放心要么是原始模型库命令行难用、没人帮你封装。ChatTTS-UI 的定位很清晰本地运行所有文本处理与语音合成都在你机器上完成数据不出门隐私可控即开即用启动后自动打开浏览器填文本、选音色、点按钮就能听到合成语音并下载 wav 文件有 API同一套服务提供/tts接口方便你把语音合成能力集成进其他系统中英混读中文、英文、数字、符号混杂的文本也能智能处理比如“iPhone 15 的发布会将于 2026 年 9 月举办”这类句子数字会被正确读出。一句话总结它是把 ChatTTS 语音合成引擎包成了“网页 API”双入口的本地小服务适合内容创作者、独立开发者也适合想在私有环境部署离线语音合成方案的小团队。第二节5 分钟跑通——本地一键启动你的第一个文字转语音服务这个项目提供了三条启动路径按你的环境挑一条即可。路径 AWindows 预打包版最省事如果你是 Windows 用户、不想碰 Python直接使用项目发布的预打包版下载压缩包、解压、双击app.exe浏览器会自动打开http://127.0.0.1:9966就这么简单。需要提醒的是某些安全软件可能对打包程序误报介意的话就用下面的源码部署。路径 B源码部署Linux / macOS / Windows 通用推荐给想长期使用、后续要改参数或做二次开发的你。核心步骤如下# 1. 克隆项目 git clone https://gitcode.com/GitHub_Trending/ch/ChatTTS-ui # 2. 进入项目目录 cd ChatTTS-ui # 3. 创建并激活虚拟环境Python 3.9-3.11推荐 3.10 python3 -m venv venv source ./venv/bin/activate # Windows 下用 .\venv\scripts\activate # 4. 安装依赖 pip3 install -r requirements.txt # 5. 安装 PyTorchCPU 版有 NVIDIA 显卡且显存大于 4G 可装 CUDA 版 pip3 install torch2.7.1 torchaudio2.7.1 # 6. 启动 python3 app.py看到Start:127.0.0.1:9966的输出后浏览器打开http://127.0.0.1:9966在文本框输入“你好欢迎使用本地语音合成服务”点“立即合成声音”几秒后就能听到你的第一段合成语音——现在就启动你的第一个本地语音合成服务吧。 首次启动会自动下载模型约 2GB程序会先探测能否连接 huggingface.co不可用时自动改用阿里魔塔 modelscope.cn。注意从 modelscope 下载时请关闭代理否则容易报 ProxyError。路径 CDocker 容器部署适合服务器如果你要把服务跑在云服务器上一条命令即可拉起容器git clone https://gitcode.com/GitHub_Trending/ch/ChatTTS-ui cd ChatTTS-ui docker compose -f docker-compose.cpu.yaml up -d容器启动后同样访问IP:9966即可。无 GPU 的机器用 CPU 版镜像有 GPU 换docker-compose.gpu.yaml。第三节按需调优——让声音更像你想要的样子跑通只是开始接下来把声音调成你想要的样子。这里先建立一个认知音色文件就是“声音的身份证”。ChatTTS 用一串数字表示一种声音特征把它保存成文件就成了一张可以反复使用的“身份证”。3.1 音色从哪里来项目根目录的speaker/文件夹就是音色库里面全是2222.csv、7869.csv这类文件。你可以直接用项目自带的音色编号如2222、7869、6653、4099、5099在网页的“音色值”输入框里填一个自定义种子值如3000、9000系统会按该值生成一套随机音色下载第三方 csv / pt 音色文件放进speaker/目录即可被自动识别。⚠️ 注意不同设备上相同音色值最终合成的声音可能有差异同一设备相同音色值多次生成也可能有细微变化尤其音调这是模型特性不必惊慌。另外0.96 版本之后内核升级从旧站点下载的seed_xxx_emb.pt旧格式音色文件不能直接用。此时执行python cover-pt.py脚本会把speaker/下以seed_开头、_emb.pt结尾的文件转换成新的*-covert.pt格式转换后可删掉原文件。3.2 Prompt 控制符给声音加戏在 Prompt 框里填入控制符可以让朗读更生动。例如[oral_2][laugh_0][break_6][laugh_0]加入笑声[break_6]加入停顿[oral_2]加入语气词/口语感3.3 核心参数组合清晰版 vs 自然版网页和 API 共用同一套采样参数含义如下参数作用默认值temperature随机性0.00001–1.0越低越稳定0.3top_p核采样范围0.1–0.90.7top_k采样候选数1–2020speed语速1–95两个经过验证的组合直接照抄清晰播报temperature0.2, top_p0.8, speed6 自然对话temperature0.5, top_p0.9, speed43.4 .env 环境配置改地址、切设备用记事本打开项目根目录的.env文件可以调整三项核心配置WEB_ADDRESS127.0.0.1:9966 # Web 服务地址与端口 compilefalse # 关闭编译优化遇 triton 报错时改为 false devicedefault # 可手动指定 cpu | mps | cuda想让局域网内其他设备访问把WEB_ADDRESS改成0.0.0.0:9966或你的局域网 IP有 NVIDIA 显卡且显存大于 4G、装了 CUDA 12.8程序默认会用 GPU 加速显存不足 4G 时会被强制使用 CPU。第四节进阶集成——把语音合成变成可调用的 API 接口网页手动点按钮只是热身真正的价值在于你的任何程序都能通过 HTTP 接口调用它这正是“语音合成 API 接口”的玩法。4.1 接口调用示例接口地址为http://127.0.0.1:9966/ttsGET / POST 均可参数以表单或查询串提交参数说明text必填要合成语音的文字voice可选音色编号默认 2222custom_voice可选自定义音色种子值大于 0 的整数设置后忽略 voiceprompt可选笑声/停顿等控制符temperature / top_p / top_k可选采样参数默认 0.3 / 0.7 / 20speed可选语速 1–9默认 5skip_refine可选1跳过文本优化wav可选设为 1 时直接返回音频文件而非 JSON下面这段 Python 代码可以直接跑import requests res requests.post(http://127.0.0.1:9966/tts, data{ text: 你好欢迎使用本地语音合成 API 服务今天是2026年8月18日。, voice: 3333, # 音色编号或用 custom_voice 传种子值 prompt: [laugh_0], # 加一点笑声 temperature: 0.3, top_p: 0.7, top_k: 20, speed: 5, skip_refine: 0 }) print(res.json())成功时返回{ code: 0, msg: ok, audio_files: [ { filename: …/static/wavs/xxxx.wav, url: http://127.0.0.1:9966/static/wavs/xxxx.wav, inference_time: 3.21, audio_duration: 5.02 } ] }拿到url后就能直接播放或下载。想省掉 JSON 解析直接把参数里的wav设为1接口会返回原始 wav 音频。4.2 批量合成与清理批量场景下把多段文本逐行提交即可每行独立合成一段。合成产生的 wav 文件存放在static/wavs/目录调用POST /clear_wavs可以一键清空这些临时文件避免磁盘被占满。4.3 一个真实的集成场景假设你在做一个资讯播报小工具用脚本抓取新闻 → 逐条调用/tts生成语音 → 拼接成音频流 → 输出到播放器。全程无需打开浏览器服务端稳定跑在 9966 端口即可。这就是“本地语音合成 API 集成”的完整闭环。第五节避坑速查表——遇到报错先看这里把高频报错和对应的解决方式整理成一张表卡住了直接查报错现象原因与解决办法Dynamo is not supported on Python 3.12项目不支持 Python 3.12降级到 Python 3.10 重装环境Missing spk_stat.ptmodelscope 上的模型缺这个文件手动获取spk_stat.pt后放到models/pzc163/chatTTS/asset/目录ProxyError: HTTPSConnectionPool(hostwww.modelscope.cn...)从 modelscope 下载模型时不可使用代理请关闭代理重试cannot find a working triton installation打开.env把compiletrue改为compilefalseFileNotFoundError: …/config/path.yaml模型不完整重新下载模型或补全models/pzc163/chatTTS/config/下的配置文件Windows 能运行但很慢若是 NVIDIA 显卡确认 CUDA 已升级到 12.8并安装对应 CUDA 版 PyTorch关于离线语音合成方案先在联网机器上运行一次python3 app.py确保模型完整下载到models/pzc163/chatTTS目录之后把整个项目含 models 目录拷贝到内网机器并按项目文档把模型加载逻辑改为直接读取本地目录即可。具体修改方式以项目 faq.md 的说明为准。第六节高频疑问快答Q1中英文和数字混杂能正常读吗能。项目内置文本预处理会把中文里的数字转为中文读法如 123 → 一二三英文里的数字转为英文读法如 123 → one two three中英混合文本按行切分处理长句超过 200 字还会自动按标点拆分。Q2必须联网才能用吗首次启动需要联网下载模型。模型下载完成后配合离线部署调整即可在内网环境使用本地语音合成服务。Q3没有 NVIDIA 显卡能用吗能。CPU 也能合成只是速度较慢macOS 可用 MPS 加速。显存大于 4G 的 NVIDIA 显卡才会启用 CUDA 加速。Q4生成的文件在哪生成的 wav 默认保存在static/wavs/目录可通过返回的 url 下载日志写在logs/目录按日期生成文件。第七节行动清单——从读到做只差这几步把今天的内容收敛成一张可勾选的清单照着做完你的本地语音合成服务就正式上线了☐ 选择启动路径Windows 预打包 / 源码部署 / Docker完成部署☐ 首次启动并确认模型下载完成打开http://127.0.0.1:9966☐ 在网页合成一段测试语音试听并下载☐ 用自定义音色种子值或 speaker 目录的音色文件找到你喜欢的声音☐ 调 temperature / top_p / speed固定一套适合自己的参数组合☐ 跑通/ttsAPI 调用返回正常 JSON☐ 需要时修改.env开放局域网访问或按离线方案部署到内网。如果你只是想给视频配个音第 1–4 步就够了如果你想把它变成产品的一部分第 5–7 步会带你把“文字转语音”能力真正用起来。这就是 ChatTTS-UI 的完整价值让本地语音合成从“折腾一天”变成“5 分钟上手”并且随时可以升级成 API 服务接入你正在做的任何东西。想给你的下一个项目加一个会说话的功能吗现在就开始吧。【免费下载链接】ChatTTS-ui一个简单的本地网页界面使用ChatTTS将文字合成为语音同时支持对外提供API接口。A simple native web interface that uses ChatTTS to synthesize text into speech, along with support for external API interfaces.项目地址: https://gitcode.com/GitHub_Trending/ch/ChatTTS-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
