IndexTTS‑2高清音质接口对接文档

模型：IndexTTS‑2 专业会员版，支持音色复刻、4 种情感控制模式，支持非流式 JSON 返回 与流式二进制音频流返回两种输出方式。

一、基础信息

1. 请求头认证

请求头	值	必填	说明
Content‑Type	application/json	是	请求体 JSON 格式
Authorization	Bearer {你的API‑KEY}	是	身份鉴权密钥，替换为平台分配的 key

2. 输出模式说明

通过stream_mode控制返回形式，业务推荐优先使用 **stream_mode:true**流式模式：

1. stream_mode: false（默认）：非流式，返回 JSON 结构，返回音频可访问下载地址audio_url。

2. stream_mode: true：流式模式，HTTP 直接返回audio/wav二进制音频流；合成字符数、扣费金额从自定义响应 Header 读取：X‑Characters、X‑Cost。

流式模式前端开发提示：服务端返回 Access‑Control‑Expose‑Headers: X‑Characters, X‑Cost，浏览器端才能正常读取这两个自定义响应头。

二、四种调用模式（互斥，仅可选择其中一种）

公共基础字段说明

• input：string，必填，待合成文本。

• prompt_audio_url：string，必填，https 协议公网可访问的音色参考音频 URL，用于复刻说话人音色。

• prompt_text：string，选填，参考音频对应的文字内容，用于语义对齐，默认为空字符串。

• stream_mode：boolean，选填，是否流式输出，默认false。

• failover_enabled：boolean，选填，是否开启故障转移降级，生产环境建议保持默认true。

模式一：基础音色模式（无情感控制 mode=none）

仅复刻参考音频音色，不对语音做额外情感干预。

请求体示例

{
    "input": "欢迎使用IndexTTS语音合成系统，这是一个默认模式的示例。",
    "prompt_audio_url": "https://xxx/sample.mp3",
    "prompt_text": "欢迎使用语音合成系统。",
    "stream_mode": true,
    "failover_enabled": true
}

模式二：音频情感控制（mode=audio）

提取参考音频中的情绪风格叠加到目标音色，四种模式中情感优先级最高。

新增必填参数：

• emo_audio_prompt_url：https 公网 URL，情感参考音频地址

• emo_alpha：0.0‑1.0，步长 0.1，情感作用强度，默认 0.5。数值越大，情绪对生成语音影响越强。

请求体示例

{
    "input": "今天心情真好，阳光明媚！",
    "prompt_audio_url": "https://xxx/spk.mp3",
    "prompt_text": "欢迎使用语音合成系统。",
    "emo_audio_prompt_url": "https://xxx/emotion.wav",
    "emo_alpha":0.8,
    "stream_mode":false
}

模式三：文本情感控制（mode=text）

通过文本描述指定合成语音的情绪、语气风格。

新增必填参数：

• use_emo_text：布尔值，必须固定填写为true

• emo_text：非空字符串，描述期望的情绪语气

请求体示例

{
    "input": "今天真是太开心了！",
    "prompt_audio_url":"https://xxx/spk.mp3",
    "prompt_text":"欢迎使用语音合成系统。",
    "use_emo_text":true,
    "emo_text":"高兴的语气，充满活力",
    "stream_mode":false
}

模式四：向量情感控制（mode=vector）

8 维情绪向量做精细化情感调控，向量顺序固定：[happy, angry, sad, afraid, disgusted, melancholic, surprised, calm]，每一项取值范围0‑1.0，步长 0.1。

• emo_vector：支持 8 位数字数组，也可传入 JSON 格式字符串

• emo_alpha：0.0‑1.0，情感影响强度，默认 0.5

请求体示例

{
    "input":"这是一个悲伤的故事",
    "prompt_audio_url":"https://xxx/spk.mp3",
    "prompt_text":"欢迎使用语音合成系统。",
    "emo_vector":[0.1,0,0.8,0,0,0.7,0,0.2],
    "emo_alpha":0.6,
    "stream_mode":false
}

三、返回结果

1、非流式模式 stream_mode=false（JSON 返回）

成功响应示例

{
    "code": 200,
    "message": "语音合成成功",
    "data": {
        "task_id": "tts_sync_67f8a9b0c1d2e",
        "status": "completed",
        "char_count": 26,
        "cost": 0.01,
        "mode": "none",
        "audio_url": "https://xxx/speech‑xxx.wav",
        "message": "语音合成成功"
    }
}

data 字段	说明
task_id	任务唯一 ID，问题排查时提供给服务商
status	同步接口固定返回completed
char_count	本次计费统计字符数量
cost	本次扣费金额，单位元
mode	none/audio/text/vector，对应四种工作模式
audio_url	wav 格式音频公网下载链接

2、流式模式 stream_mode=true（二进制音频）

HTTP 响应头：

HTTP/1.1 200 OK
Content‑Type: audio/wav
X‑Characters: 26
X‑Cost: 0.01
Access‑Control‑Expose‑Headers: X‑Characters, X‑Cost

响应 Body 直接输出 wav 二进制音频流，不会返回 JSON 结构体。

浏览器 JS 流式调用示例

fetch('https://www.yuntts.com/api/v1/text-to-speech', {
    method: 'POST',
    headers: {
        'Content‑Type': 'application/json',
        'Authorization': 'Bearer your‑api‑key'
    },
    body: JSON.stringify({
        input: '你好',
        prompt_audio_url: 'https://example.com/sample.wav',
        stream_mode: true
    })
}).then(async r => {
    const blob = await r.blob();
    const audio = new Audio(URL.createObjectURL(blob));
    audio.play();
    console.log(`字符数: ${r.headers.get('X‑Characters')}，费用: ${r.headers.get('X‑Cost')}元`);
});

四、错误码对照表

错误响应统一 JSON 格式：{"code": number,"error":"错误标识","message":"可读错误描述"}

code	error 字段	message 说明	对接处理建议
400	empty_text	请输入要合成的文本	input 参数不能为空字符串
400	missing_prompt_audio	请提供说话人音色参考音频 URL	prompt_audio_url 必须是可公网访问 https 链接
400	missing_emo_text	使用文本情感控制需要提供 emo_text	模式三必须传emo_text并且use_emo_text=true
400	invalid_vector	情感向量格式错误，应为包含 8 个数值的数组	emo_vector 严格为 8 个 0‑1 之间数字
400	invalid_vector_value	情感向量第 N 个值超出范围，应为 0.0~1.0	校验向量每个元素取值区间
401	-	认证失败	检查 Authorization Bearer 的 API‑KEY 是否正确
402	insufficient_balance	余额不足，需要 xx 元，当前余额 xx 元	前往平台账户充值
405	method_not_allowed	仅支持 POST 请求	HTTP 请求方法修改为 POST
500	save_failed	音频文件保存失败，已退款	服务内部异常，直接重试，该场景不会扣费

错误响应示例

{"code": 402, "error": "insufficient_balance", "message": "余额不足，需要0.01元，当前余额0.00元"}

五、对接重要注意事项

1. prompt_audio_url、emo_audio_prompt_url必须为公网可访问 https 链接，禁止传入本地文件路径、内网地址。

2. 四种模式参数互斥，禁止同时传入多套模式参数，例如不要同时传递emo_audio_prompt_url与emo_text。

3. 流式模式响应体是 wav 二进制，不能按 JSON 解析；计费与字符统计信息全部读取 HTTP 响应头。

4. failover_enabled=true开启故障转移，主链路异常自动降级，线上业务建议保持开启。

5. emo_alpha情感权重，过高会破坏原始音色，推荐业务取值区间 0.3‑0.8。

6. 向量模式 8 个情绪顺序不可变更：[happy, angry, sad, afraid, disgusted, melancholic, surprised, calm]。

六、cURL 完整调用示例

示例 1：基础音色模式，流式输出保存 wav 文件

curl --location --request POST 'https://www.yuntts.com/api/v1/text-to-speech' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content‑Type: application/json' \
--data-raw '{
    "input":"测试语音合成",
    "prompt_audio_url":"https://xxx/spk.mp3",
    "stream_mode":true
}' --output output.wav

示例 2：音频情感模式，非流式获取音频 URL

curl --location --request POST 'https://www.yuntts.com/api/v1/text-to-speech' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content‑Type: application/json' \
--data-raw '{
    "input":"今天真是开心的一天",
    "prompt_audio_url":"https://xxx/spk.mp3",
    "emo_audio_prompt_url":"https://xxx/happy.wav",
    "emo_alpha":0.6,
    "stream_mode":false
}'