创建语音合成任务

二、创建文生语音任务

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 写法（顺序固定：高兴、愤怒、悲伤、恐惧、厌恶、低落、惊讶、平静）

[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 时使用，三种方式任选其一）

参数	类型	必填	说明
`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：最简（默认情绪）

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

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

{
  "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：文本情绪（最自然）

{
  "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：向量情绪（单一：低落/温柔）

{
  "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：向量情绪（混合：悲伤 + 低落）

{
  "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 音素

{
  "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：关闭情绪（用音色本身语气）

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

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

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

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

示例 10：用克隆好的音色

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

curl 跑通流程

常见错误

常见错误	返回	正确做法
给英文单词配 `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	轮询提示

返回示例

{
  "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`	任务写入失败，请稍后重试

application/json

Bodyapplication/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.1 四种调用模式

2.2 请求参数

2.3 请求示例

2.4 返回参数

2.5 错误码

请求参数

请求示例代码

返回响应

创建语音合成任务

二、创建文生语音任务#

2.1 四种调用模式#

2.2 请求参数#

2.3 请求示例#

2.4 返回参数#

2.5 错误码#

请求参数

请求示例代码

返回响应

二、创建文生语音任务

2.1 四种调用模式

2.2 请求参数

2.3 请求示例

2.4 返回参数

2.5 错误码