IndexTTS-2.5 语音合成 API 接口使用文档

前言说明

IndexTTS 2.5 是基于 IndexTTS2 迭代升级的零样本多语言情感语音合成模型，依靠短音频参考即可完成音色克隆，支持中文、英文、日语、西班牙语、阿拉伯语五种语言生成，可跨语言迁移音色与情感；模型将 S2M 模块主干升级为 Zipformer，压缩语义编码帧率并引入 GRPO 强化学习优化发音，推理速度提升至原版 2.28 倍，在保留音色相似度的同时增强自然度，还提供喜、悲、怒、平静等情感预设以及多档语速调节，适合多语种旁白、短视频配音、有声书等场景，支持在线 API 调用与本地！

一、接入说明

1.1 接口地址

1.2在线调试

本在线调试功能仅供接口调试使用，如需完整请求参数，请参考相关接口文档。

1.3 鉴权

每个请求都必须带请求头：

Authorization: Bearer {你的API密钥}

1.4 请求体格式

1.5返回结构

成功（HTTP 200）

{
  "code": 200,
  "message": "任务已提交",
  "data": { }
}

失败（HTTP 状态码与 code 相同）

{
  "code": 400,
  "error": "empty_text",
  "message": "请输入要合成的文本（text）"
}

• code：HTTP 状态码
• message：给人看的提示文案
• error：给程序判断的错误代码（失败时才有）
• data：业务数据（成功时才有）

1.6 通用错误码

二、创建文生语音任务

POST https://www.yuntts.com/api/v1/indextts25/submit

• 权限：仅会员（VIP / 永久会员），普通用户返回 403 permission_denied
• 并发：同一账号进行中的任务最多 10 个，超出返回 429 too_many_tasks

2.1 四种调用模式

2.2 请求参数

正文

音色

语言与语速

情绪控制

情绪向量 emotion_vector 写法（顺序固定：高兴、愤怒、悲伤、恐惧、厌恶、低落、惊讶、平静）

[0, 0, 0.6, 0, 0, 0.2, 0, 0]

也可以按维度名传：

{ "sad": 0.6, "melancholic": 0.2 }

规则：每个维度 0 ~ 0.8，总和必须大于 0 且不超过 0.8，不能为 null。

参考音频（voice_source=asset 时使用，三种方式任选其一）

参考音频格式要求

• 支持格式：WAV / MP3 / FLAC / OGG / M4A（地址方式需以对应扩展名结尾）
• 单个文件 ≤ 15MB，时长 0.5 ~ 15 秒
• 建议清晰人声、无背景音乐

自定义读音（可选，最多 100 条，同一个 word 不能重复）

词语和读音都不能包含 < > | 或控制字符。

2.3 请求示例

模式一：基础音色

{
  "text": "欢迎使用 IndexTTS 2.5 语音合成服务。",
  "voice_source": "preset",
  "voice_id": "01a0a95d-9255-79a5-9050-4eca1064620d",
  "language": "ZH",
  "speed": 1.0,
  "emotion_mode": "default",
  "pronunciations": [
    { "word": "重庆", "kind": "pinyin", "value": "chong2 qing4" }
  ]
}

模式二：文本情绪

{
  "text": "今天真是太开心了！",
  "voice_source": "preset",
  "voice_id": "01a0a95d-9255-79a5-9050-4eca1064620d",
  "emotion_mode": "text",
  "emotion_description": "亲切热情，像在和朋友聊天",
  "emotion_strength": 0.8
}

模式三：向量情绪

{
  "text": "这是一个悲伤的故事。",
  "voice_source": "preset",
  "voice_id": "01a0a95d-9255-79a5-9050-4eca1064620d",
  "emotion_mode": "vector",
  "emotion_vector": [0, 0, 0.6, 0, 0, 0.2, 0, 0],
  "emotion_vector_mode": "mixed"
}

模式四：给音频地址（不用上传文件）

{
  "text": "这是用参考音频合成的示例。",
  "voice_source": "asset",
  "reference_audio_url": "https://www.yuntts.com/tools/tts/reference.wav",
  "duration_ms": 5000,
  "save_voice": true,
  "voice_name": "我的音色",
  "language": "ZH"
}

模式四：上传音频文件（multipart/form-data）

说明：multipart 方式下所有非文件字段都填字符串，布尔值填 true / false，数组填 JSON 字符串（如 [0.5,0,0,0,0,0,0,0]）。

2.4 返回参数

返回示例

{
  "code": 200,
  "message": "任务已提交",
  "data": {
    "task_id": "indextts25_api_68f2c1a0b3d47_1790984300",
    "status": "pending",
    "model": "IndexTTS-2.5",
    "char_count": 36,
    "billable_chars": 30,
    "points_deducted": 0.02,
    "voice_source": "preset",
    "save_voice": false,
    "voice_name": "",
    "poll_hint": "请调用 /indextts25/status 轮询，传本 task_id 即可"
  }
}

2.5 错误码

三、查询单个任务

POST https://www.yuntts.com/api/v1/indextts25/status

建议每 3~5 秒查询一次；任务结束后会直接返回结果，不会重复计算。

3.1 请求参数

3.2 返回参数

合成中的返回

{
  "code": 200,
  "message": "任务进行中",
  "data": {
    "task_id": "indextts25_api_68f2c1a0b3d47_1790984300",
    "status": "running",
    "progress": 60,
    "audio_url": "",
    "char_count": 36,
    "billable_chars": 30,
    "points_deducted": 0.02,
    "error_message": "",
    "created_at": "2026-10-03 10:00:00",
    "finished_at": null
  }
}

合成成功的返回

{
  "code": 200,
  "message": "合成成功",
  "data": {
    "task_id": "indextts25_api_68f2c1a0b3d47_1790984300",
    "status": "completed",
    "progress": 100,
    "audio_url": "https://www.yuntts.com/wp-content/uploads/my-document/audio/processed/1790984300_30859541.wav",
    "char_count": 36,
    "billable_chars": 30,
    "points_deducted": 0.02,
    "error_message": "",
    "created_at": "2026-10-03 10:00:00",
    "finished_at": "2026-10-03 10:00:20",
    "service_point_cost": 12
  }
}

3.3 任务状态

pending ──► running ──► completed
                │
                ├──► failed ──► refunded（自动退款）
                └──► cancelled ──► refunded（自动退款）

3.4 错误码

四、取消任务

POST https://www.yuntts.com/api/v1/indextts25/cancel

任务开始生成之前可以取消；已经结束的任务不能取消。取消成功后预扣积分会自动退回。

4.1 请求参数

4.2 返回参数

{
  "code": 200,
  "message": "已取消",
  "data": {
    "task_id": "indextts25_api_68f2c1a0b3d47_1790984300",
    "status": "refunded"
  }
}

4.3 错误码

五、查询音色列表

POST https://www.yuntts.com/api/v1/indextts25/voices

返回可直接使用的音色：系统音色 + 你自己创建的音色。别人的克隆音色看不到。

5.1 请求参数

5.2 返回参数

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "items": [
      {
        "voice_id": "01a0a95d-9255-79a5-9050-4eca1064620d",
        "name": "承泽",
        "source": "preset",
        "voice_source": "official",
        "description": "IndexTTS2.5 系统预设音色",
        "model": "IndexTTS-2.5",
        "model_permission": 1,
        "audio_url": "https://www.yuntts.com/wp-content/uploads/my-document/audio/processed/1790984194_35515870.wav",
        "avatar_url": "https://www.yuntts.com/wp-content/uploads/avatar-tss/ai.webp",
        "created_at": "2026-10-03 09:00:00"
      }
    ],
    "total": 1,
    "source": "local_database"
  }
}

5.3 错误码

六、创建自定义音色（声音克隆）

POST https://www.yuntts.com/api/v1/indextts25/clone

• 权限：仅会员。普通用户返回 403 permission_denied
• 数量上限：VIP 10 个，永久会员不限，其他 2 个；超出返回 403 model_limit_exceeded
• 参考音频可以上传文件，也可以给一个公网音频地址

6.1 请求参数

参考音频要求：WAV / MP3 / FLAC / OGG / M4A，≤15MB，时长 0.5 ~ 15 秒，建议清晰人声、无背景音乐。

给音频地址的方式

{
  "name": "我的音色",
  "describe": "参考音频克隆",
  "voice_url": "https://www.yuntts.com/tools/tts/reference.wav",
  "duration_ms": 6000
}

上传文件的方式（multipart/form-data）

6.2 返回参数

{
  "code": 200,
  "message": "音色创建成功",
  "data": {
    "voice_id": "01a0a970-3c11-7d22-8b55-6c8f1e3a9d22",
    "name": "我的音色",
    "source": "custom",
    "audio_url": "https://www.yuntts.com/wp-content/uploads/my-document/audio/original/1790984400_12345678.wav",
    "avatar_url": "https://www.yuntts.com/wp-content/uploads/avatar-tss/ai.webp",
    "asset_id": "asset_01a0a96f",
    "saved_to": "local_database"
  }
}

创建成功后音色立即可用：创建任务时传 voice_source=custom + 该 voice_id 即可。

6.3 错误码

七、删除自定义音色

POST https://www.yuntts.com/api/v1/indextts25/delete-voice

只能删除自己创建的音色；系统音色不能删除。

7.1 请求参数

7.2 返回参数

{
  "code": 200,
  "message": "音色已删除（远端 + 本地）",
  "data": {
    "voice_id": "01a0a970-3c11-7d22-8b55-6c8f1e3a9d22",
    "deleted": true
  }
}

7.3 错误码

八、计费说明

字符数对照（自检用）

九、快速上手

9.1 调用流程

1. 取音色        POST /indextts25/voices     拿到 voice_id
   （可选）      POST /indextts25/clone      先克隆一个自己的音色
2. 提交任务      POST /indextts25/submit     保存返回的 task_id
3. 轮询结果      POST /indextts25/status     每 3~5 秒查一次
   ├─ completed  → 用 audio_url 播放或下载
   └─ failed / cancelled / refunded → 看 error_message，积分已退回
4. 需要时        POST /indextts25/cancel     取消任务并退款
5. 需要时        POST /indextts25/delete-voice 删除不用的克隆音色

9.2 完整示例（curl）

BASE="https://www.yuntts.com/api/v1"
KEY="你的API密钥"

# 1) 取音色列表
curl -X POST "$BASE/indextts25/voices" 
  -H "Authorization: Bearer $KEY" 
  -H "Content-Type: application/json" 
  -d '{}'

# 2) 提交任务（基础音色）
curl -X POST "$BASE/indextts25/submit" 
  -H "Authorization: Bearer $KEY" 
  -H "Content-Type: application/json" 
  -d '{
        "text": "你好，这是 IndexTTS 2.5 的合成测试。",
        "voice_source": "preset",
        "voice_id": "音色ID",
        "language": "ZH",
        "speed": 1.0,
        "emotion_mode": "default"
      }'

# 2b) 提交任务（文本情绪）
curl -X POST "$BASE/indextts25/submit" 
  -H "Authorization: Bearer $KEY" 
  -H "Content-Type: application/json" 
  -d '{
        "text": "今天真是太开心了！",
        "voice_id": "音色ID",
        "emotion_mode": "text",
        "emotion_description": "亲切热情"
      }'

# 2c) 提交任务（参考音频：给地址，免上传）
curl -X POST "$BASE/indextts25/submit" 
  -H "Authorization: Bearer $KEY" 
  -H "Content-Type: application/json" 
  -d '{
        "text": "这是用参考音频合成的示例。",
        "voice_source": "asset",
        "reference_audio_url": "https://www.yuntts.com/tools/tts/reference.wav",
        "duration_ms": 5000,
        "save_voice": true,
        "voice_name": "我的音色"
      }'

# 2d) 提交任务（参考音频：上传文件）
curl -X POST "$BASE/indextts25/submit" 
  -H "Authorization: Bearer $KEY" 
  -F "text=这是用参考音频合成的示例。" 
  -F "voice_source=asset" 
  -F "duration_ms=6000" 
  -F "reference_audio_file=@./ref.wav"

# 3) 查询任务
curl -X POST "$BASE/indextts25/status" 
  -H "Authorization: Bearer $KEY" 
  -H "Content-Type: application/json" 
  -d '{"task_id":"上一步返回的 task_id"}'

# 4) 克隆音色（上传文件）
curl -X POST "$BASE/indextts25/clone" 
  -H "Authorization: Bearer $KEY" 
  -F "name=我的音色" 
  -F "duration_ms=6000" 
  -F "voice_file=@./ref.wav"

# 4b) 克隆音色（给音频地址）
curl -X POST "$BASE/indextts25/clone" 
  -H "Authorization: Bearer $KEY" 
  -H "Content-Type: application/json" 
  -d '{
        "name": "我的音色",
        "voice_url": "https://www.yuntts.com/tools/tts/reference.wav",
        "duration_ms": 6000
      }'

# 5) 删除音色
curl -X POST "$BASE/indextts25/delete-voice" 
  -H "Authorization: Bearer $KEY" 
  -H "Content-Type: application/json" 
  -d '{"voice_id":"音色ID"}'

9.3 轮询建议

• 间隔 3~5 秒，不要低于 2 秒
• 单条音频一般 10~60 秒完成，长文本会更久
• 判断结束：data.status 不是 pending 和 running 时即可停止轮询
• 页面/程序关闭后任务仍会继续，稍后再查也能拿到结果

十、常见问题

Q：提示「语音合成服务接口密钥未配置，请联系管理员」怎么办？
A：这是站点侧配置问题，与你的密钥无关，请联系管理员处理。

Q：duration_ms 一定要传吗？
A：不一定。音频地址或文件是 WAV / MP3 时会自动解析时长；FLAC / OGG / M4A 请显式传入。

Q：能给内网或本机地址吗？
A：不能。reference_audio_url / voice_url 只接受公网可访问的 http/https 直链，内网地址会被拒绝。

Q：任务成功但 audio_url 是空的？
A：说明音频还没保存完成或保存失败，请稍后重试查询；我们会在服务端记录具体原因。

Q：积分什么时候扣、什么时候退？
A：提交任务时预扣，任务成功不退还；失败、取消、任务不存在都会自动全额退回。

Q：最多能同时跑几个任务？
A：同一账号进行中的任务最多 10 个，超出会返回 too_many_tasks。

Q：能创建几个克隆音色？
A：VIP 10 个，永久会员不限，其他 2 个。

Q：克隆音色做好后能给别人用吗？
A：音色属于创建者账号，其他人查询不到，也不能使用。

Q：删除音色后，用它合成的音频会消失吗？
A：不会。已合成并保存的音频不受影响，只是该音色不能再用于新的合成任务。