IndexTTS-2-LLM API文档解析：请求参数与返回格式详解
1. 为什么你需要关注这个API
你有没有遇到过这样的情况：想快速把一篇产品说明转成语音发给客户，却发现手头的TTS工具要么声音生硬像机器人，要么要配GPU服务器、装一堆依赖，折腾半天还跑不起来？
IndexTTS-2-LLM不是又一个“理论上很美”的模型镜像——它真正在解决一个实际问题：在普通CPU机器上，用最简流程，生成真正听得舒服的语音。
这不是传统TTS的简单升级，而是把大语言模型对语言节奏、停顿、重音的理解能力，直接注入到语音波形生成中。结果是什么？一句话：“你好，欢迎光临”不再是一板一眼的播报，而是带呼吸感、有轻重缓急、甚至能听出一点微笑语气的真实人声。
本文不讲论文公式，也不堆砌技术参数。我们只聚焦一件事：当你准备调用它的API时，到底该传什么、怎么传、收到什么、怎么用。所有内容基于真实部署环境验证，代码可复制、参数可直用、错误可排查。
2. API基础信息与调用准备
2.1 接口地址与协议
API服务默认运行在镜像启动后的本地端口（通常为http://127.0.0.1:7860），对外提供标准 RESTful 接口。
你不需要额外配置反向代理或网关，只要镜像正常运行，HTTP服务就已就绪。
- 基础URL：
http://<你的服务地址>/tts - 请求方法：
POST - 请求头（Headers）：
Content-Type: application/json（必须）Accept: application/json（建议）
注意：该API不依赖认证Token，也无需API Key。这是为快速集成设计的轻量级接口，适用于内网可信环境。如需生产级鉴权，可在Nginx层自行添加。
2.2 环境准备检查清单
在写第一行代码前，请确认以下三点已满足：
- 镜像已成功启动，WebUI页面可正常访问（地址栏输入服务地址应看到语音合成界面）
- 浏览器开发者工具（F12）→ Network 标签页中，能看到
/tts请求被正常发起（用于后续调试） - 你使用的编程语言支持发送 JSON POST 请求（Python、JavaScript、curl 均原生支持，无需额外库）
如果你用的是 Python，推荐使用requests库（极简示例）：
import requests url = "http://127.0.0.1:7860/tts" headers = {"Content-Type": "application/json"}3. 请求参数详解：每个字段都值得细读
3.1 必填参数：决定语音是否能“开口”
| 参数名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
text | string | 是 | 要转换的文本内容。支持中英文混合，长度建议 ≤ 500 字符（过长可能触发截断或超时） |
speaker | string | 是 | 发声人标识。当前支持两个值： • "default"：基于 IndexTTS-2-LLM 主模型生成，自然度高，适合通用场景• "sambert"：调用阿里 Sambert 引擎备用通道，稳定性强，适合长文本或高并发 |
常见误区提醒：
- 不要传空字符串
""或纯空格，会返回400 Bad Requestspeaker值区分大小写，"Default"或"SAMBERT"均无效- 中文标点（，。！？）会被正确识别为停顿点，无需额外加空格
3.2 可选参数：让声音更贴合你的需求
| 参数名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
speed | number | 1.0 | 语速调节系数。0.8为偏慢（适合教学/老年用户），1.2为偏快（适合资讯播报），范围0.5–2.0 |
pitch | number | 0.0 | 音调偏移量。-2.0到+2.0，负值更低沉，正值更高亢。对中文影响明显，对英文较弱 |
volume | number | 1.0 | 音量增益。0.5为半音量，1.5为1.5倍音量，范围0.1–2.0 |
format | string | "wav" | 输出音频格式。仅支持"wav"和"mp3"。"mp3"文件更小，但首次生成稍慢（需编码耗时） |
实用技巧：
- 想让客服语音听起来更亲切？试试
speed=0.9,pitch=0.3- 生成有声书旁白？
speed=0.85,volume=1.1让声音更有沉浸感- 批量生成时优先用
"wav"，避免MP3编码引入额外延迟
3.3 完整请求示例（含注释）
payload = { "text": "今天天气不错，适合出门散步。", "speaker": "default", "speed": 0.95, "pitch": 0.2, "volume": 1.05, "format": "wav" } response = requests.post(url, json=payload, headers=headers)这段代码会生成一段约3秒的高质量中文语音，语速略缓、音调微扬、音量饱满——就像一位温和的真人主播在轻声讲述。
4. 返回格式与状态码：读懂服务的每一种回应
4.1 成功响应（HTTP 200）
当一切顺利时，API返回一个标准 JSON 对象，结构清晰、字段明确：
{ "code": 0, "message": "success", "data": { "audio_url": "/audio/20240521_142318_default.wav", "duration": 3.24, "text": "今天天气不错，适合出门散步。", "speaker": "default" } }code: 业务状态码，0表示成功message: 可读提示，供前端展示或日志记录data.audio_url:最关键字段——这是音频文件的相对路径。你只需将它拼接到服务基础地址后，即可得到完整可播放链接，例如：http://127.0.0.1:7860/audio/20240521_142318_default.wavdata.duration: 预估音频时长（秒），可用于前端进度条初始化data.text与data.speaker: 回显原始请求参数，便于审计与调试
小技巧：浏览器直接打开
audio_url链接即可试听；程序中可用requests.get()下载二进制音频流保存为文件。
4.2 常见错误响应与排查指南
| HTTP状态码 | code值 | message示例 | 原因与解决方案 |
|---|---|---|---|
400 | 1001 | "text is empty" | text字段为空或只含空白字符 → 检查前端输入框是否为空、后端是否做了trim处理 |
400 | 1002 | "invalid speaker" | speaker值不是"default"或"sambert"→ 检查拼写、大小写、引号是否为英文 |
400 | 1003 | "text too long" | 文本超过500字符 → 前端做字数限制，或后端按句号/换行符自动分段 |
500 | 5001 | "tts engine error" | 模型推理异常（如内存不足、依赖冲突）→ 查看服务日志，确认CPU内存≥4GB，重启镜像 |
503 | — | Service Unavailable | 服务未启动或端口被占用 → 进入镜像容器执行ps aux | grep python确认进程存活 |
调试黄金法则：
打开浏览器开发者工具 → Network → 点击任意一次“🔊 开始合成” → 找到/tts请求 → 查看Headers（确认请求头）、Payload（确认发送内容）、Response（确认返回体）、Preview（直观查看JSON结构）。90%的参数问题，一眼就能定位。
5. 实战：三步完成语音批量生成脚本
光看文档不如动手一次。下面是一个真实可用的 Python 脚本，帮你把多段文案批量转成语音并自动保存：
5.1 脚本功能说明
- 读取
scripts.txt文件（每行一段待合成文本） - 依次调用API，使用
default声音、wav格式 - 生成的音频按顺序命名为
output_001.wav,output_002.wav… - 自动创建
./audio/目录存放结果
5.2 完整可运行代码
import requests import time import os # 配置 API_URL = "http://127.0.0.1:7860/tts" HEADERS = {"Content-Type": "application/json"} OUTPUT_DIR = "./audio" # 创建输出目录 os.makedirs(OUTPUT_DIR, exist_ok=True) # 读取脚本 with open("scripts.txt", "r", encoding="utf-8") as f: texts = [line.strip() for line in f if line.strip()] print(f"共读取 {len(texts)} 段文案，开始批量合成...") for i, text in enumerate(texts, 1): payload = { "text": text, "speaker": "default", "format": "wav" } try: response = requests.post(API_URL, json=payload, headers=HEADERS, timeout=60) result = response.json() if result.get("code") == 0: audio_url = "http://127.0.0.1:7860" + result["data"]["audio_url"] audio_data = requests.get(audio_url).content filename = f"output_{i:03d}.wav" filepath = os.path.join(OUTPUT_DIR, filename) with open(filepath, "wb") as f: f.write(audio_data) print(f" {i:3d}/{len(texts)} | '{text[:20]}...' → 已保存为 {filename}") else: print(f"❌ {i:3d}/{len(texts)} | 错误: {result.get('message', '未知错误')}") except Exception as e: print(f"💥 {i:3d}/{len(texts)} | 请求异常: {str(e)}") # 避免请求过于密集（可选） time.sleep(0.5) print(f"\n 批量任务完成！音频文件已存至 {OUTPUT_DIR}")5.3 使用前准备
- 新建文件
scripts.txt，内容如下（UTF-8编码）：欢迎使用智能语音合成服务。 本系统支持中英文混合输入。 语音自然流畅，适合多种场景。 - 确保镜像正在运行，且
http://127.0.0.1:7860可访问 - 运行脚本，等待控制台打印完成提示
进阶提示：
- 如需导出MP3，只需将
format改为"mp3"，文件扩展名同步改为.mp3- 如需指定不同发音人，可在
texts列表中为每项增加speaker字段（需修改payload构造逻辑）- 日志中 ``
❌💥符号便于快速识别状态（实际生产环境建议替换为标准日志库）
6. 总结：API不是终点，而是起点
IndexTTS-2-LLM 的 API 设计，本质上是在“强大能力”和“易用门槛”之间找到了一个务实平衡点。它没有用 OAuth2、JWT、Webhook 等复杂机制制造障碍，而是用最朴素的 JSON POST，把高质量语音合成的能力，交到每一个想用它的人手里。
你已经掌握了：
- 如何构造合法请求（
text和speaker是命脉） - 如何解读返回结果（
audio_url是关键钥匙） - 如何排查典型错误（从 400 到 503 的实战对照表）
- 如何落地为生产力（批量脚本开箱即用）
下一步，你可以把它嵌入企业知识库的语音播报模块，接入客服对话系统的自动应答，或者做成内部培训材料的自动配音工具。真正的价值，永远不在API文档里，而在你用它解决的第一个实际问题中。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
