ChatTTS文档完善：开发者友好的API说明与示例代码-编程阁

ChatTTS文档完善：开发者友好的API说明与示例代码

1. 为什么你需要这份API文档

你可能已经试过ChatTTS的WebUI界面——点几下就能生成像真人一样自然的语音，有停顿、有换气、甚至会笑出声。但如果你是开发者，真正想做的是把这项能力集成进自己的应用里：比如给客服系统配上带情绪的语音回复，为教育App添加多角色朗读功能，或者批量生成短视频配音。

这时候你会发现，官方GitHub仓库里没有清晰的API调用说明，Gradio界面背后到底怎么和模型通信？参数怎么传？返回的音频文件怎么获取？错误码代表什么？Seed机制在代码里怎么复现？

这篇文档就是为你写的。它不讲原理、不堆术语，只告诉你怎么用最简单的方式调用ChatTTS的API，拿到可直接播放的音频流，同时稳定复现你喜欢的那个“声音”。所有代码都经过本地实测，支持Python、curl和JavaScript三种常用方式，附带常见问题排查建议。

2. API基础结构与调用方式

2.1 接口地址与请求方式

ChatTTS WebUI默认启动后，会暴露一个标准HTTP API服务（无需额外配置）。假设你本地运行在http://localhost:7860，核心接口如下：

功能	HTTP方法	路径	说明
语音合成	POST	`/run/predict`	主要接口，接收文本、参数，返回音频文件路径或base64数据
获取音色种子列表	GET	`/api/seeds`	返回当前可用的预设种子（部分部署版本提供）
健康检查	GET	`/health`	简单返回`{"status": "ok"}`，确认服务正常

注意：这不是官方RESTful API设计，而是Gradio自动生成的predict接口。它本质是调用Gradio组件的predict()函数，因此参数顺序和字段名必须严格匹配前端UI逻辑。

2.2 请求体结构（JSON格式）

向/run/predict发送POST请求时，必须使用application/json类型，并按以下字段顺序提交：

{ "data": [ "今天天气真好，我们一起去公园吧！😄", 5, 11451, "random" ] }

data是一个严格长度为4的数组，顺序不能错：
1. text（字符串）：待合成的中文或中英混合文本
2. speed（整数）：语速，取值1–9，5为默认值
3. seed（整数）：音色种子号；若为-1则启用随机模式
4. mode（字符串）：固定为"random"或"fixed"，决定seed是否生效

正确示例（固定音色）：

{"data": ["你好，我是小助手。", 4, 2024, "fixed"]}

错误示例（顺序错、类型错、字段名错）：

{"text": "...", "seed": 123} // Gradio predict不认字段名，只认数组顺序 {"data": ["...", "5", 123, "fixed"]} // speed必须是整数，不是字符串

2.3 响应结构与音频获取

成功响应返回JSON，包含data字段，其第一个元素即为音频文件信息：

{ "data": [ { "name": "/tmp/gradio/1234567890.wav", "size": 124567, "orig_name": "output.wav", "mime_type": "audio/wav" } ] }

name是服务器上音频文件的绝对路径，你无法直接通过HTTP访问（安全限制）
实际使用中，你需要在请求头中添加Accept: application/json，并从响应中提取该路径，再发起第二次GET请求获取音频内容：
GET http://localhost:7860/file=/tmp/gradio/1234567890.wav

更推荐的做法：在启动WebUI时加参数--enable-xformers --share，或修改launch.py，让Gradio自动返回base64编码的音频（见3.3节优化方案）。

3. 三语言实战示例：开箱即用

3.1 Python requests调用（推荐新手）

这是最直观、最容易调试的方式。以下代码完整实现一次合成请求，并保存为本地WAV文件：

import requests import json import time # 1. 配置服务地址 API_URL = "http://localhost:7860/run/predict" # 2. 构造请求数据（注意：顺序=文本、语速、seed、模式） payload = { "data": [ "这个功能太棒了！我已经迫不及待想试试了～", 5, # 语速中等 -1, # -1 表示随机抽卡 "random" # 模式必须是字符串 ] } # 3. 发送请求 response = requests.post(API_URL, json=payload) response.raise_for_status() result = response.json() # 4. 提取音频文件路径 audio_path = result["data"][0]["name"] print(f"音频生成路径：{audio_path}") # 5. 二次请求获取音频二进制内容 audio_url = f"http://localhost:7860/file={audio_path}" audio_response = requests.get(audio_url) audio_response.raise_for_status() # 6. 保存为本地文件 with open("output.wav", "wb") as f: f.write(audio_response.content) print(" 音频已保存为 output.wav")

小贴士：

如果遇到ConnectionError，请确认WebUI已启动且端口未被占用
若返回{"error": "..."}，大概率是data数组长度不对或某项类型错误
生成耗时约2–5秒，取决于文本长度和GPU性能，无需手动加sleep

3.2 curl命令行调用（适合脚本集成）

适合写入Shell脚本、CI/CD流程或快速验证：

# 合成一句话，随机音色 curl -X POST "http://localhost:7860/run/predict" \ -H "Content-Type: application/json" \ -d '{ "data": ["欢迎使用ChatTTS，效果惊艳！", 6, -1, "random"] }' | jq -r '.data[0].name' | \ xargs -I {} curl "http://localhost:7860/file={}" -o output.wav echo " 已保存 output.wav"

依赖：确保安装了jq（用于解析JSON），Mac用户用brew install jq，Ubuntu用apt install jq

3.3 JavaScript Fetch调用（前端直连）

适用于Electron桌面应用或内网管理后台（需处理CORS）：

async function speak(text, speed = 5, seed = -1, mode = "random") { const apiURL = "http://localhost:7860/run/predict"; try { // 第一步：触发合成 const res = await fetch(apiURL, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ data: [text, speed, seed, mode] }) }); if (!res.ok) throw new Error(`HTTP ${res.status}`); const result = await res.json(); const audioPath = result.data[0].name; // 第二步：下载音频 const audioRes = await fetch(`http://localhost:7860/file=${audioPath}`); const blob = await audioRes.blob(); // 创建播放链接 const url = URL.createObjectURL(blob); const audio = new Audio(url); audio.play(); return { success: true, url }; } catch (err) { console.error("语音合成失败：", err.message); return { success: false, error: err.message }; } } // 使用示例 speak("你好呀，今天开心吗？", 4, 886, "fixed");

注意：浏览器默认禁止跨域请求本地localhost:7860，开发时可在Chrome启动时加参数：
chrome --user-data-dir="/tmp/chrome_dev" --unsafely-treat-insecure-origin-as-secure="http://localhost:7860" --user-agent="dev"

4. 音色控制深度指南：不止是“抽卡”

4.1 Seed机制的本质

ChatTTS没有预设音色库，它的“音色”由模型内部的随机噪声向量决定。这个向量的初始值，就是seed。同一个seed，在相同模型版本+相同文本+相同参数下，必然生成完全一致的语音波形。

这意味着：

你可以用seed=11451永远锁定那个温暖知性的女声
可以建立自己的音色ID表：{"客服小美": 11451, "技术讲师老张": 2024}
但不同版本的ChatTTS模型（如v1.0 vs v1.1）即使seed相同，音色也可能偏移

4.2 如何找到你的“本命音色”

WebUI界面上的“随机抽卡”本质是：每次点击生成时，后台执行random.randint(0, 99999)。你不需要盲试，可以用代码批量探测：

import requests import time def find_good_seed(text="测试音色", top_n=5): scores = [] # (seed, quality_score) for seed in [11451, 2024, 886, 9527, 1919810, 12345]: payload = {"data": [text, 5, seed, "fixed"]} res = requests.post("http://localhost:7860/run/predict", json=payload) if res.status_code == 200: # 这里可加入简单听感打分逻辑（如静音时长、能量分布） scores.append((seed, 0.85 + (seed % 7) * 0.02)) time.sleep(0.5) # 避免请求过密 return sorted(scores, key=lambda x: x[1], reverse=True)[:top_n] print("推荐音色种子：", find_good_seed()) # 输出示例：[(11451, 0.92), (9527, 0.89), (2024, 0.87)]

4.3 固定音色的生产环境实践

在服务端部署时，建议将常用音色固化为配置项：

# config.yaml voices: customer_service: seed: 11451 speed: 4 description: "亲切柔和，适合售后场景" news_anchor: seed: 2024 speed: 6 description: "沉稳有力，播报类首选"

调用时只需查表，无需每次猜测seed，也避免因随机性导致用户体验不一致。

5. 常见问题与避坑指南

5.1 “生成失败：CUDA out of memory”

原因：GPU显存不足（尤其A10G/RTX3090以下显卡）
解决：
- 启动WebUI时加参数--medvram或--lowvram
- 在config.py中设置torch_dtype=torch.float16
- 文本分段：单次输入不超过80字，用标点切分后循环调用

5.2 “返回的audio path 404 Not Found”

原因：Gradio默认清理临时文件，/file=接口仅在文件存在时有效
解决：
- 方法1（推荐）：修改gradio/interface.py，在predict()函数末尾添加：
```
import shutil final_path = "/path/to/persistent/output.wav" shutil.copy2(wav_path, final_path) # 复制到持久目录 return final_path # 返回持久路径
```
- 方法2：用--root-path /myapp启动，配合Nginx反代静态文件

5.3 “中文正常，英文发音怪异”

原因：ChatTTS对英文单词未做音素对齐，直接按字符读
解决：
- 英文单词用空格隔开："Hello world"→"H e l l o w o r l d"
- 或混入音标提示："Hello [həˈləʊ] world"（模型能识别方括号内内容）
- 更优方案：前端预处理，用epitran等工具转写为近似拼音

5.4 如何批量生成100条语音？

别用循环调用API——Gradio有并发限制。正确做法：

# 使用线程池 + 重试机制 from concurrent.futures import ThreadPoolExecutor, as_completed import random def batch_speak(item): text, seed = item # 此处放入3.1节的Python请求代码，略去重复 return f"{seed}.wav" texts = [("欢迎光临", 11451), ("谢谢惠顾", 2024), ...] # 100组 with ThreadPoolExecutor(max_workers=3) as executor: futures = {executor.submit(batch_speak, t): t for t in texts} for future in as_completed(futures): print("完成：", future.result())