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

基本说明

IndexTTS 2.5 是在 IndexTTS2 基础上迭代升级的零样本多语言情感语音合成模型，依托Zipformer架构、语义编解码压缩与GRPO强化学习优化，推理速度提升至原来的2.28倍，在保留音色相似度与发音准确率的同时大幅降低算力开销。它支持中文、英文、日语、西班牙语、阿拉伯语五种语言，仅需一段简短参考音频即可完成音色克隆，还可跨语言迁移情感，提供喜、怒、哀、平静等情绪预设以及多档语速调节，适合多语种旁白、短视频配音等场景，兼顾自然度、可控性与推理效率。

一、接入说明

1.1 接口地址

接口	完整请求地址	说明
创建任务	`https://www.yuntts.com/api/v1/indextts25/submit`	创建文生语音任务
查询任务	`https://www.yuntts.com/api/v1/indextts25/status`	查询单个任务
取消任务	`https://www.yuntts.com/api/v1/indextts25/cancel`	取消任务
删除任务	`https://www.yuntts.com/api/v1/indextts25/delete-task`	删除任务
音色列表	`https://www.yuntts.com/api/v1/indextts25/voices`	查询可用音色
创建音色	`https://www.yuntts.com/api/v1/indextts25/clone`	声音克隆，创建自定义音色
删除音色	`https://www.yuntts.com/api/v1/indextts25/delete-voice`	删除自定义音色

1.2 鉴权

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

复制代码

Authorization: Bearer {你的API密钥}

情况	返回
没带请求头	`401 缺少Authorization请求头`
格式不是 `Bearer xxx`	`401 Authorization头格式错误`
密钥无效	`401 API密钥无效`

1.3 请求体格式

接口	Content-Type
创建任务	`application/json`（推荐）；需要提交音频文件时用 `multipart/form-data`
查询 / 取消 / 音色列表 / 删除音色	`application/json`
创建音色	`multipart/form-data`（提交文件）或 `application/json`（只给音频地址）

1.4 返回结构

成功（HTTP 200）

json 复制代码

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

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

json 复制代码

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

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

1.5 通用错误码

HTTP	error	说明
401	`rest_forbidden` / `rest_invalid_auth` / `rest_missing_api_key` / `rest_invalid_api_key`	鉴权失败
405	`method_not_allowed`	用了 GET 访问
500	`missing_api_key`	服务接口密钥未配置，请联系管理员
502	`service_error`	语音服务调用异常，可稍后重试

二、创建文生语音任务

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

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

2.1 四种调用模式

模式	音色来源	情绪控制	必须传
模式一基础音色	系统音色 / 我的克隆音色	自动	`text` + `voice_id`
模式二文本情绪	系统音色 / 我的克隆音色	情绪文本描述	`text` + `voice_id` + `emotion_description`
模式三向量情绪	系统音色 / 我的克隆音色	8 维情绪向量	`text` + `voice_id` + `emotion_vector`
模式四参考音频	一段参考音频（可顺带存为我的音色）	自动 / 文本 / 向量	`text` +（`reference_audio_url` 或上传文件或 `asset_id`）

2.2 请求参数

正文

参数	类型	必填	说明
`text`	String	是	要合成的文本，最多 2000 个字符，且至少包含一个汉字、字母或数字

音色

参数	类型	必填	说明
`voice_source`	String	否	`preset` 系统音色（默认）、`custom` 我的克隆音色、`asset` 临时参考音频
`voice_id`	String	条件必填	音色 ID，`voice_source=preset/custom` 时必填（从音色列表接口获取）

语言与语速

参数	类型	必填	说明
`language`	String	否	`ZH` 中文（默认）、`EN` 英语、`JA` 日语、`ES` 西班牙语、`AR` 阿拉伯语；填错自动回退 `ZH`
`speed`	Number	否	语速 `0.5 ~ 2.0`，默认 `1.0`，超出范围自动裁剪

情绪控制

参数	类型	必填	说明
`emotion_mode`	String	否	`default` 自动推断（默认）、`text` 情绪文本、`vector` 情绪向量、`off` 关闭情绪控制
`emotion_description`	String	条件必填	情绪描述文本，最多 200 字；`emotion_mode=text` 时必填，如「亲切热情，像在和朋友聊天」
`emotion_strength`	Number	否	情绪强度 `0 ~ 1`，默认 `0.8`
`emotion_vector`	Array / Object	条件必填	8 维情绪向量，`emotion_mode=vector` 时必填，见下方说明
`emotion_vector_mode`	String	否	`single` 单一情绪、`mixed` 混合情绪；不传时按非零维度数量自动判断

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

json 复制代码

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

也可以按维度名传：

json 复制代码

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

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

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

参数	类型	必填	说明
`reference_audio_url`	String	三选一	公网可访问的音频直链，由本站抓取后使用；仅支持公网地址，单文件 ≤15MB
`reference_audio_file`	File	三选一	直接上传音频文件（`multipart/form-data` 方式），格式与大小要求同上
`asset_id`	String	三选一	已经登记过的素材 ID
`duration_ms`	Integer	否	音频时长（毫秒，`500 ~ 15000`）；不传时 WAV / MP3 会自动解析，其它格式请显式传入
`save_voice`	Boolean	否	是否把这段参考音频同时保存为可复用的自定义音色，默认 `false`
`voice_name`	String	条件必填	保存音色的名称，最多 64 字；`save_voice=true` 时必填

参考音频格式要求

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

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

参数	类型	必填	说明
`pronunciations[].word`	String	是	正文中的目标词语，1 ~ 64 字；`kind=pinyin` 时必须是汉字
`pronunciations[].kind`	String	是	`pinyin` 拼音、`alias` 别名替换、`cmu` 英文音素、`kana` 日文假名
`pronunciations[].value`	String	是	指定读音，1 ~ 512 字

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

kind	word 必须是	读音写法	示例
`pinyin`	只能是汉字（英文单词会报错）	拼音音节，空格分隔；音节数 = 汉字数，每音节带 1~5 声调	`{"word":"重庆","kind":"pinyin","value":"chong2 qing4"}`
`cmu`	英文单词	CMU / ARPAbet 音素，空格分隔	`{"word":"read","kind":"cmu","value":"R IY1 D"}`
`alias`	任意词（缩写、专有名词等）	用一段文字引导读音	`{"word":"API","kind":"alias","value":"诶屁爱"}`
`kana`	日文词（汉字或假名）	片假名读音	`{"word":"今日","kind":"kana","value":"キョウ"}`

⚠️ 常见错误：给英文单词配 kind=pinyin 会返回 400 invalid_pronunciations（pinyin 只接受汉字）。英文请用 cmu，其它文字用 alias。

2.3 请求示例

下面示例统一用系统音色小新：voice_id = 01a08fcc-63f2-7a9e-8ce1-a654e2d3241f（想看有哪些音色，调 /indextts25/voices）。

示例 1：最简（默认情绪）

json 复制代码

{
  "text": "你好，我是小新，很高兴认识你。",
  "voice_source": "preset",
  "voice_id": "01a08fcc-63f2-7a9e-8ce1-a654e2d3241f"
}

示例 2：中文 + 语速 + 自定义读音

json 复制代码

{
  "text": "欢迎来到重庆，这里的火锅很有名。",
  "voice_source": "preset",
  "voice_id": "01a08fcc-63f2-7a9e-8ce1-a654e2d3241f",
  "language": "ZH",
  "speed": 0.9,
  "emotion_mode": "default",
  "pronunciations": [
    {
      "word": "重庆",
      "kind": "pinyin",
      "value": "chong2 qing4"
    },
    {
      "word": "API",
      "kind": "alias",
      "value": "诶屁爱"
    }
  ]
}

示例 3：文本情绪（最自然）

json 复制代码

{
  "text": "今天天气真好，我们出去玩吧！",
  "voice_source": "preset",
  "voice_id": "01a08fcc-63f2-7a9e-8ce1-a654e2d3241f",
  "language": "ZH",
  "speed": 1.1,
  "emotion_mode": "text",
  "emotion_description": "开心、活泼，像在和孩子说话",
  "emotion_strength": 0.9
}

示例 4：向量情绪（单一：低落/温柔）

json 复制代码

{
  "text": "别担心，一切都会好起来的。",
  "voice_source": "preset",
  "voice_id": "01a08fcc-63f2-7a9e-8ce1-a654e2d3241f",
  "emotion_mode": "vector",
  "emotion_vector": [
    0,
    0,
    0,
    0,
    0,
    0.5,
    0,
    0
  ],
  "emotion_vector_mode": "single",
  "emotion_strength": 0.8
}

示例 5：向量情绪（混合：悲伤 + 低落）

json 复制代码

{
  "text": "再见了，我的朋友。",
  "voice_source": "preset",
  "voice_id": "01a08fcc-63f2-7a9e-8ce1-a654e2d3241f",
  "emotion_mode": "vector",
  "emotion_vector": [
    0,
    0,
    0.4,
    0,
    0,
    0.3,
    0,
    0
  ],
  "emotion_vector_mode": "mixed",
  "emotion_strength": 0.7
}

示例 6：英文 + CMU 音素

json 复制代码

{
  "text": "Please read this sentence for me.",
  "voice_source": "preset",
  "voice_id": "01a08fcc-63f2-7a9e-8ce1-a654e2d3241f",
  "language": "EN",
  "speed": 1,
  "emotion_mode": "default",
  "pronunciations": [
    {
      "word": "read",
      "kind": "cmu",
      "value": "R IY1 D"
    }
  ]
}

示例 7：关闭情绪（用音色本身语气）

json 复制代码

{
  "text": "本次列车开往人民广场，请站稳扶好。",
  "voice_source": "preset",
  "voice_id": "01a08fcc-63f2-7a9e-8ce1-a654e2d3241f",
  "emotion_mode": "off"
}

示例 8：参考音频（给音频地址，不用上传文件）

json 复制代码

{
  "text": "这是用参考音频合成的效果。",
  "voice_source": "asset",
  "reference_audio_url": "https://www.yuntts.com/tools/tts/reference.wav",
  "duration_ms": 5000,
  "language": "ZH"
}

示例 9：参考音频 + 同时保存为我的音色（multipart/form-data）

bash 复制代码

curl -X POST "https://www.yuntts.com/api/v1/indextts25/submit" \
  -H "Authorization: Bearer {你的API密钥}" \
  -F "text=这是用参考音频合成的示例。" \
  -F "voice_source=asset" \
  -F "reference_audio_file=@./reference.wav" \
  -F "duration_ms=5000" \
  -F "save_voice=true" \
  -F "voice_name=我的旁白音色" \
  -F "language=ZH"

示例 10：用克隆好的音色

json 复制代码

{
  "text": "我已经把音色保存下来了，之后可以直接使用。",
  "voice_source": "custom",
  "voice_id": "创建音色接口返回的 voice_id",
  "emotion_mode": "default"
}

curl 跑通流程

bash 复制代码

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

# 1) 提交合成
curl -X POST "$BASE/indextts25/submit" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "text": "你好，我是小新，很高兴认识你。",
        "voice_source": "preset",
        "voice_id": "01a08fcc-63f2-7a9e-8ce1-a654e2d3241f"
      }'

# 2) 每 3~5 秒查询一次（task_id 用上一步返回值）
curl -X POST "$BASE/indextts25/status" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"上一步返回的 task_id"}'

常见错误

常见错误	返回	正确做法
给英文单词配 `kind=pinyin`	`400 invalid_pronunciations`	英文用 `kind=cmu`（如 `read → R IY1 D`），其它文字用 `alias`
`save_voice=true` 但没给 `voice_name`	`400 missing_voice_name`	两者成对出现，且仅 `voice_source=asset` 时有效
向量总和超过 0.8 / `single` 却有多个非零维度	`400 invalid_emotion`	每维 ≤0.8、总和 ≤0.8；`single` 恰好一个非零
`voice_source=asset` 既没给文件也没给地址	`400 missing_asset`	上传文件、给 `reference_audio_url`、或传 `asset_id` 三选一
用 GET 调用	`405 method_not_allowed`	所有接口都是 POST

2.4 返回参数

参数	类型	说明
`data.task_id`	String	任务 ID，用于查询和取消
`data.status`	String	提交后固定为 `pending`（排队中）
`data.model`	String	模型标识
`data.char_count`	Integer	本次计费字符数（汉字算 2，其他字符算 1）
`data.billable_chars`	Integer	对账用字符数（只统计字母和数字），不参与扣费
`data.points_deducted`	Number	本次预扣积分
`data.voice_source`	String	本次使用的音色来源
`data.save_voice`	Boolean	是否同时保存了音色
`data.voice_name`	String	保存的音色名称
`data.poll_hint`	String	轮询提示

返回示例

json 复制代码

{
  "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 错误码

HTTP	error	说明
400	`empty_text`	正文为空
400	`text_too_long`	正文超过 2000 字符
400	`invalid_text`	正文里没有任何汉字、字母或数字
400	`missing_voice`	没传 `voice_id`
400	`missing_asset`	参考音频模式：文件、音频地址、`asset_id` 都没给
400	`invalid_audio_url`	音频地址不是公网 http/https 直链、下载失败或格式不符
400	`missing_voice_name` / `invalid_voice_name`	`save_voice=true` 没填名称 / 名称超过 64 字
400	`invalid_emotion`	情绪参数不合法（描述为空、向量维度或数值越界等）
400	`invalid_pronunciations`	读音规则不合法
400	`invalid_payload`	请求参数组装失败
400	`upload_failed`	参考音频格式、大小或时长不符合要求
402	`insufficient_balance`	积分不足
403	`permission_denied`	不是会员
429	`too_many_tasks`	进行中任务太多
500	`database_error`	任务写入失败，请稍后重试

三、查询单个任务

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

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

3.1 请求参数

参数	类型	必填	说明
`task_id`	String	是	创建任务时返回的 `task_id`

3.2 返回参数

参数	类型	说明
`data.task_id`	String	任务 ID
`data.status`	String	任务状态，见 3.3
`data.progress`	Integer	进度百分比：排队 30、合成中 60、完成 100
`data.audio_url`	String	音频文件地址（本站存储，可直接播放或下载）；任务未完成或保存失败时为空字符串
`data.char_count`	Integer	本次计费字符数
`data.billable_chars`	Integer / null	对账用字符数，不参与扣费
`data.points_deducted`	Number	本次预扣积分
`data.error_message`	String	失败或取消原因；成功时为空字符串
`data.created_at`	String	创建时间
`data.finished_at`	String / null	完成时间；未完成时为 `null`
`data.service_point_cost`	Integer	仅合成成功时返回：本次计费点数（对账用）

合成中的返回

json 复制代码

{
  "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
  }
}

合成成功的返回

json 复制代码

{
  "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 任务状态

status	含义	该怎么处理
`pending`	排队中	继续轮询
`running`	合成中	继续轮询
`completed`	合成完成	用 `audio_url` 播放或下载
`failed`	合成失败	读 `error_message`，积分已自动退回
`cancelled`	已取消	积分已自动退回
`refunded`	已退款	失败或取消后的终态，积分已退回

复制代码

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

3.4 错误码

HTTP	error	说明
400	`missing_task_id`	没传 `task_id`
404	`task_not_found`	任务不存在，或不属于当前账号
502	`service_error`	查询异常，任务状态不受影响，可继续轮询
502	`unknown_status`	出现了无法识别的任务状态，请联系管理员

四、取消任务

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

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

4.1 请求参数

参数	类型	必填	说明
`task_id`	String	是	创建任务时返回的 `task_id`

4.2 返回参数

参数	类型	说明
`data.task_id`	String	任务 ID
`data.status`	String	取消成功固定为 `refunded`（已退款）

json 复制代码

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

4.3 错误码

HTTP	error	说明
400	`missing_task_id`	没传 `task_id`
400	`task_finished`	任务已结束，无法取消
404	`task_not_found`	任务不存在，或不属于当前账号
502	`cancel_failed`	取消失败（任务可能已经开始生成）

五、删除任务

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

只能删除已经结束的任务（合成完成 / 失败 / 已取消）；进行中的任务请先取消或等它结束。

注意：删除后云端生成的音频文件会被删除，已经消耗的积分不会退回。

5.1 请求参数

参数	类型	必填	说明
`task_id`	String	是	创建任务时返回的 `task_id`

5.2 返回参数

参数	类型	说明
`data.task_id`	String	被删除的任务 ID
`data.deleted`	Boolean	固定为 `true`
`data.remote_deleted`	Boolean	是否已同时删除云端任务

json 复制代码

{
  "code": 200,
  "message": "任务已删除",
  "data": {
    "task_id": "indextts25_api_68f2c1a0b3d47_1790984300",
    "deleted": true,
    "remote_deleted": true
  }
}

5.3 错误码

HTTP	error	说明
400	`missing_task_id`	没传 `task_id`
400	`task_not_finished`	任务还没结束，请先取消或等待完成
404	`task_not_found`	任务不存在，或不属于当前账号
500	`database_error`	本地记录删除失败，请稍后重试
502	`delete_failed`	删除失败，可稍后重试

六、查询音色列表

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

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

6.1 请求参数

参数	类型	必填	说明
`voice_source`	String	否	`official` 只看系统音色、`upload` 只看我的克隆音色；不传返回全部

6.2 返回参数

参数	类型	说明
`data.items`	Array	音色列表（系统音色在前，我的克隆音色在后）
`data.items[].voice_id`	String	音色 ID，创建任务时传给 `voice_id`
`data.items[].name`	String	音色名称
`data.items[].source`	String	`preset` 系统音色 / `custom` 克隆音色，可直接作为创建任务的 `voice_source`
`data.items[].voice_source`	String	`official` 系统 / `upload` 我的克隆
`data.items[].description`	String	音色描述
`data.items[].model`	String	所属模型
`data.items[].model_permission`	Integer	权限标记
`data.items[].audio_url`	String	试听地址（本站存储）；没有试听样例时为空字符串
`data.items[].avatar_url`	String	头像地址
`data.items[].created_at`	String	创建时间
`data.total`	Integer	音色数量
`data.source`	String	数据来源标记

json 复制代码

{
  "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"
  }
}

6.3 错误码

HTTP	error	说明
500	`database_error`	音色查询失败，请稍后重试

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

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

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

7.1 请求参数

参数	类型	必填	说明
`name`	String	是	音色名称，最多 64 字
`describe`	String	否	音色描述，最多 500 字
`duration_ms`	Integer	否	音频时长（毫秒，`500 ~ 15000`）；不传时 WAV / MP3 会自动解析
`voice_file`	File	二选一	上传参考音频文件（`multipart/form-data`）
`voice_url`	String	二选一	公网参考音频直链（`application/json` 方式），仅支持公网地址

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

给音频地址的方式

json 复制代码

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

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

字段	值
name	我的音色
describe	参考音频克隆
duration_ms	6000
voice_file	（选择文件）

7.2 返回参数

参数	类型	说明
`data.voice_id`	String	新音色 ID，可直接用于创建任务
`data.name`	String	音色名称
`data.source`	String	固定为 `custom`
`data.audio_url`	String	试听地址（本站存储）
`data.avatar_url`	String	头像地址
`data.asset_id`	String	参考音频素材 ID
`data.saved_to`	String	数据落库标记

json 复制代码

{
  "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 即可。

7.3 错误码

HTTP	error	说明
400	`missing_name` / `invalid_name`	没填名称 / 名称超过 64 字
400	`missing_file`	既没上传 `voice_file`，也没给 `voice_url`
400	`invalid_audio_url`	音频地址不是公网 http/https 直链、下载失败或格式不符
400	`upload_failed`	音频格式、大小或时长不符合要求
403	`permission_denied`	不是会员
403	`model_limit_exceeded`	音色数量已达上限
500	`database_error`	音色写入失败，请稍后重试
502	`service_error`	创建音色失败，可稍后重试

八、删除自定义音色

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

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

8.1 请求参数

参数	类型	必填	说明
`voice_id`	String	是	要删除的音色 ID（必须是自己创建的克隆音色）

8.2 返回参数

参数	类型	说明
`data.voice_id`	String	被删除的音色 ID
`data.deleted`	Boolean	固定为 `true`

json 复制代码

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

8.3 错误码

HTTP	error	说明
400	`missing_voice_id`	没传 `voice_id`
403	`not_deletable`	系统音色不允许删除
403	`permission_denied`	无权删除别人的音色
404	`voice_not_found`	音色不存在
502	`service_error`	删除失败，可稍后重试

九、计费说明

项	规则
计费字符数	1 个汉字算 2 个字符（简体、繁体、日文汉字、韩文汉字）；其他字符（字母、数字、标点、空格、日文假名、韩文字母）各算 1 个字符
积分计算	`积分 = 计费字符数 × 单价 ÷ 10000 × 会员折扣`；先抵扣会员免费额度，超出部分才扣积分
免费额度	API 通道使用独立的免费额度
退款	合成失败、主动取消、任务不存在，都会自动全额退回预扣积分
查询余额	可在站点会员中心查看积分余额

字符数对照（自检用）

文本	计费字符数
你好	4
中A文123	8
中文。	5
中文。	6

示例文本的字符数对照 （可用来自检返回的 char_count）：

示例	文本	计费字符数	对账字符	基础积分（6 元/万字符，未含会员折扣）
1	你好，我是小新，很高兴认识你。	27	12	0.0162
2	欢迎来到重庆，这里的火锅很有名。	30	14	0.0180
3	今天天气真好，我们出去玩吧！	26	12	0.0156
4	别担心，一切都会好起来的。	24	11	0.0144
5	再见了，我的朋友。	16	7	0.0096
6	Please read this sentence for me.	33	27	0.0198
7	本次列车开往人民广场，请站稳扶好。	32	15	0.0192
8	这是用参考音频合成的效果。	25	12	0.0150
9	这是用参考音频合成的示例。	25	12	0.0150
10	我已经把音色保存下来了，之后可以直接使用。	40	19	0.0240

十、快速上手

10.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-task  删除已结束的任务
6. 需要时        POST /indextts25/delete-voice 删除不用的克隆音色

10.2 完整示例（curl）

bash 复制代码

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-task" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"任务ID"}'

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

10.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：不会。删除只是清理任务和云端音频文件，已消费的积分不退回；需要退积分请用「取消任务」。

Q：任务还在合成中，能直接删除吗？

A：不能。请先取消或等任务结束（completed / failed / cancelled）后再删除。

Q：删除音色后，用它合成的音频会消失吗？

A：不会。已合成并保存的音频不受影响，只是该音色不能再用于新的合成任务。