IndexTTS-2 异步语音合成 API 文档

概述

IndexTTS 是一款先进的零样本文本转语音（Zero-shot TTS）系统。它具备卓越的个性化能力，无需大规模训练数据即可快速克隆说话人音色。该模型支持灵活的情感与风格控制，提供音频参考、情感向量、文本提示三种调节方式，助您生成自然、富有表现力的语音。

本文档提供 IndexTTS-2 异步语音合成接口 的完整参考。开发者可通过本接口，利用上述三种情感控制模式，轻松集成高质量的语音合成功能。

通用说明

认证方式

所有接口均需要在请求头中携带 Authorization 字段进行身份验证：

Authorization: Bearer <你的API密钥>

基础URL

https://www.yuntts.com/api/v1

响应格式

所有接口返回 JSON 格式数据。

一、语音合成接口

使用方式

模式一：默认模式（无情感控制）

原理：不传任何情感控制参数，使用默认音色合成语音。

关键参数：

• input_text：要合成的文本内容
• prompt_audio_url：说话人音色参考音频
• prompt_text：对应 prompt_audio_url 的文字内容（用于语义对齐，可选）

适用场景：不需要特殊情感控制，使用默认语气合成。

模式二：音频模式（通过音频控制语气）

原理：上传一段带有目标情绪的参考音频，模型会模仿其中的语气和韵律。

关键参数：

• emo_audio_prompt_url：情感参考音频的地址
• emo_alpha：情感影响强度（0~1，越大情绪越明显，默认0.5）
• input_text：要合成的文本内容
• prompt_audio_url：说话人音色参考音频
• prompt_text：对应 prompt_audio_url 的文字内容（用于语义对齐，可选）

适用场景：已有真实录音作为情感样例，想让模型模仿。

模式三：文本模式（通过文本控制语气）

原理：输入一段带有目标情绪的参考文本，模型会根据文字语义推断并模仿对应的语气。

关键参数：

• use_emo_text：是否启用情感参考文本（传 true）
• emo_text：表达目标情绪的参考文本
• input_text：要合成的文本内容
• prompt_audio_url：说话人音色参考音频
• prompt_text：对应 prompt_audio_url 的文字内容（用于语义对齐，可选）

适用场景：没有情感音频样例，仅通过文字引导模型生成目标情绪语音。

模式四：向量模式（通过向量控制语气）

原理：通过设置情感向量，控制合成语音中不同情绪的占比和强度。

关键参数：

• emo_vector：情感强度向量 [happy, angry, sad, afraid, disgusted, melancholic, surprised, calm]，数值范围 0~1
• emo_alpha：情感影响强度（0~1，越大情绪越明显，默认0.5）
• input_text：要合成的文本内容
• prompt_audio_url：说话人音色参考音频
• prompt_text：对应 prompt_audio_url 的文字内容（用于语义对齐，可选）

适用场景：希望精细调节合成语音的情绪比例，无需真实参考音频。

请求接口

POST https://www.yuntts.com/api/v1/indextts2_speech_generate

请求头

请求参数

基础参数

情感控制参数（四种模式互斥，都不传则为默认模式）

请求示例

模式一：默认模式（无情感控制）

不传任何情感控制参数，使用默认音色合成。

{
  "input_text": "你好，这是测试文本",
  "prompt_audio_url": "https://example.com/voice.wav",
  "prompt_text": "这是参考音频里说的话"
}

模式二：音频模式（通过音频控制语气）

传入 emo_audio_prompt_url 参数，使用情感参考音频控制输出情感。

{
  "input_text": "你好，这是测试文本",
  "prompt_audio_url": "https://example.com/voice.wav",
  "prompt_text": "这是参考音频里说的话",
  "emo_audio_prompt_url": "https://example.com/emotion.wav",
  "emo_alpha": 0.6
}

模式三：文本模式（通过文本控制语气）

传入 use_emo_text 和 emo_text 参数，使用文本描述控制情感。

{
  "input_text": "你好，这是测试文本",
  "prompt_audio_url": "https://example.com/voice.wav",
  "prompt_text": "这是参考音频里说的话",
  "use_emo_text": true,
  "emo_text": "开心、兴奋"
}

模式四：向量模式（通过向量控制语气）

传入 emo_vector 参数，使用8维情感向量精确控制情感强度。

{
  "input_text": "你好，这是测试文本",
  "prompt_audio_url": "https://example.com/voice.wav",
  "prompt_text": "这是参考音频里说的话",
  "emo_vector": "0.8, 0.1, 0.1, 0.0, 0.0, 0.0, 0.0, 0.0",
  "emo_alpha": 0.6
}

或数组格式：

{
  "input_text": "你好，这是测试文本",
  "prompt_audio_url": "https://example.com/voice.wav",
  "prompt_text": "这是参考音频里说的话",
  "emo_vector": [0.8, 0.1, 0.1, 0.0, 0.0, 0.0, 0.0, 0.0],
  "emo_alpha": 0.6
}

emo_vector 各维度含义：[happy(开心), angry(生气), sad(悲伤), afraid(害怕), disgusted(厌恶), melancholic(忧郁), surprised(惊讶), calm(平静)]

cURL 示例（音频模式）

curl -X POST "https://www.yuntts.com/api/v1/indextts2_speech_generate" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "input_text": "你好，这是测试文本",
    "prompt_audio_url": "https://example.com/voice.wav",
    "prompt_text": "这是参考音频里说的话",
    "emo_audio_prompt_url": "https://example.com/emotion.wav",
    "emo_alpha": 0.6
  }'

返回参数

返回示例

{
  "code": 200,
  "message": "任务提交成功",
  "data": {
    "task_id": "ABC123XYZ789",
    "char_count": 22,
    "cost": 0.01,
    "status": "pending"
  }
}

二、任务查询接口

请求接口

POST https://www.yuntts.com/api/v1/speech_task_status

请求头

请求参数

请求示例

curl -X POST "https://www.yuntts.com/api/v1/speech_task_status" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"task_id": "ABC123XYZ789"}'

PowerShell (Windows)

Invoke-WebRequest -Uri "https://www.yuntts.com/api/v1/speech_task_status" -Method Post -Headers @{"Authorization"="Bearer YOUR_API_KEY";"Content-Type"="application/json"} -Body '{"task_id": "ABC123XYZ789"}'

JSON 请求体

{
  "task_id": "ABC123XYZ789"
}

返回参数

返回示例

{
  "code": 200,
  "message": "获取状态成功",
  "data": {
    "task_id": "ABC123XYZ789",
    "status": "completed",
    "progress": 100,
    "message": "语音合成成功",
    "audio_url": "https://oss.example.com/audio/xxx.wav"
  }
}

三、任务取消接口

请求接口

POST https://www.yuntts.com/api/v1/speech_task_cancel

请求头

请求参数

请求示例

curl -X POST "https://www.yuntts.com/api/v1/speech_task_cancel" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"task_id": "ABC123XYZ789"}'

PowerShell (Windows)

Invoke-WebRequest -Uri "https://www.yuntts.com/api/v1/speech_task_cancel" -Method Post -Headers @{"Authorization"="Bearer YOUR_API_KEY";"Content-Type"="application/json"} -Body '{"task_id": "ABC123XYZ789"}'

JSON 请求体

{
  "task_id": "ABC123XYZ789"
}

返回参数

返回示例

{
  "code": 200,
  "message": "取消成功",
  "data": {
    "task_id": "ABC123XYZ789",
    "status": "cancelled",
    "message": "任务已取消"
  }
}

错误码说明

使用流程

1. 获取API密钥 - 在用户中心获取你的API密钥
2. 提交合成任务 - 调用 /indextts2_speech_generate，获取任务ID
3. 轮询任务状态 - 每5秒调用 /speech_task_status 查询进度
4. 获取结果 - 任务完成后返回音频URL
5. 取消任务（如需要） - 任务完成前可调用 /speech_task_cancel 取消并退款

注意事项

• 模式互斥：四种情感控制模式互斥，同时只能使用一种。如果同时传入多个情感控制参数，优先级为：音频模式 > 文本模式 > 向量模式
• emo_alpha适用范围：emo_alpha参数仅在音频模式和向量模式下有效，文本模式不需要此参数
• 情感向量模式的emo_vector参数支持JSON数组格式或逗号分隔字符串格式
• 任务完成后音频请在24小时内下载，过期自动清理
• 任务失败或取消时，已扣除的费用会自动返还到账户
• 建议轮询间隔设置为5秒，避免请求过于频繁