IndexTTS2 文生语音 API
IndexTTS2(IndexTTS-2)支持中文和英文语音生成,可使用平台预设音色、自定义音色或参考音频,并调整语速、情绪和指定词语的读音。输出为 WAV 音频。
通过 /audio/v1/* 异步接口调用:创建任务后取得 task_id,轮询任务状态,成功后从 task.output_url 下载音频。创建请求必须显式指定 "model": "indextts2";省略 model 或传空字符串时使用 IndexTTS 2.5。
模型选择与差异
| 项目 | IndexTTS2 | IndexTTS 2.5 |
|---|---|---|
model | indextts2 | indextts2.5(默认) |
language | ZH 中文、EN 英文 | ZH、EN、JA 日文、ES 西班牙语、AR 阿拉伯语 |
pronunciations[].kind | pinyin、alias | pinyin、alias、cmu、kana |
| 正文长度 | 最多 2000 个 Unicode 字符 | 最多 2000 个 Unicode 字符 |
| 语速 | 0.5~2.0 | 0.5~2.0 |
| 情绪控制 | 自动、文字描述、8 维向量、跟随参考音色 | 相同 |
模型名称区分大小写。model 是创建请求的顶层字段,与 text、voice 同级;查询任务时返回在 task.model,不在 task.input 内。
两种模型共用音色库、参考音频上传、任务管理和语音计价接口。切换模型可以继续使用已有的 voice_id 或 asset_id,但必须使用新的 Idempotency-Key。IndexTTS 2.5 的完整参数说明见 IndexTTS 2.5 文生语音 API。
接入信息
- 请求地址:
https://cp.compshare.cn。 - 鉴权:
Authorization: Bearer <YOUR_API_KEY>。 - API Key 必须是在视频工作台 左侧 API 入口创建的 MiniMax H3 模块专属模型密钥,以
sk-ml-开头。其他模块的 API Key 不能用于此接口,获取步骤见获取 API Key。 - 携带 JSON 请求体时必须设置
Content-Type: application/json。 - 创建语音任务和自定义音色时必须携带
Idempotency-Key,去除首尾空白后为 1~128 个字符,建议使用 UUID。 - 任务、参考素材、自定义音色和积分余额归属于 API Key 对应的顶级组织,与同组织工作台共享,无需传账号或组织 ID。
- 请求与成功响应使用
snake_case;未知请求体字段会报错。时间戳单位为 Unix 秒,文件大小单位为字节。
同一组织的模型 API 调用,在同一创建接口重复使用相同幂等键会复用已有资源。请求超时后请保留原键、原模型和原参数重试;创建新任务或切换模型时使用新键。跨模型复用同一语音任务幂等键会返回业务错误。
接口总览
| 功能 | 方法 | 路径 |
|---|---|---|
| 创建文生语音任务 | POST | /audio/v1/speech/jobs |
| 查询单个任务 | GET | /audio/v1/speech/jobs/{task_id} |
| 查询任务列表 | GET | /audio/v1/speech/jobs |
| 取消任务 | POST | /audio/v1/speech/jobs/{task_id}/cancel |
| 删除任务 | DELETE | /audio/v1/speech/jobs/{task_id} |
| 查询音色列表 | GET | /audio/v1/voices |
| 获取参考音频上传地址 | POST | /audio/v1/upload_urls |
| 登记参考音频素材 | POST | /audio/v1/assets |
| 创建自定义音色 | POST | /audio/v1/voices |
| 删除自定义音色 | DELETE | /audio/v1/voices/{voice_id} |
| 查询语音计价与积分余额 | GET | /audio/v1/pricing |
| 查询积分套餐包 | GET | /minimax/v2/query/point_packages |
推荐调用流程
- 查询
/audio/v1/pricing,确认enabled=true且可用积分足够。 - 查询
/audio/v1/voices?kind=preset或kind=custom,取得voice_id。 - 创建语音任务,指定
model="indextts2",保存返回的task_id。 - 每隔 3 秒查询任务,直到
succeeded、failed或cancelled。 - 成功后通过
task.output_url下载 WAV 文件。
创建文生语音任务
POST https://cp.compshare.cn/audio/v1/speech/jobs请求参数
| 名称 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| model | String | 是(选择本模型) | 必须为 indextts2;省略或传空字符串会选择 IndexTTS 2.5 | indextts2 |
| text | String | 是 | 正文,最多 2000 个 Unicode 字符,包含标点和空白;至少包含一个汉字、字母或数字 | 你好,欢迎使用优云智算。 |
| language | String | 否 | ZH 中文或 EN 英文,默认 ZH,区分大小写 | ZH |
| voice | Object | 是 | 音色引用,结构见下表 | {"source":"preset","voice_id":"<VOICE_ID>"} |
| speed | Number | 否 | 语速,范围 0.5~2.0;省略或传 0 时按 1.0 处理 | 1.0 |
| auto_emotion | Boolean | 否 | 自动推断情绪,默认 true | true |
| emotion_description | String | 否 | 情绪描述,最多 200 个字符;非空时使用描述引导情绪 | 温柔、平静,适合睡前故事 |
| emotion_strength | Number | 否 | 情绪强度,范围 0~1,默认 0.8;显式传 0 时保留零值 | 0.8 |
| emotion_vector | Array of Number | 否 | 8 维手动情绪向量,约束见下文 | [0.4,0,0,0,0,0,0,0] |
| emotion_vector_mode | String | 否 | single 或 mixed;须与 emotion_vector 一起使用 | single |
| pronunciations | Array of Object | 否 | 读音规则,最多 100 条;仅支持 pinyin、alias | [{"word":"重庆","kind":"pinyin","value":"chong2 qing4"}] |
| save_voice | Boolean | 否 | 默认 false;仅 voice.source=asset 时可设为 true,同时保存自定义音色 | false |
| voice_name | String | 条件必填 | save_voice=true 时必填,去除首尾空白后为 1~64 个字符 | 我的旁白音色 |
音色引用
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| voice.source | String | 是 | preset 平台预设音色、custom 自定义音色、asset 临时参考素材 |
| voice.voice_id | String | 条件必填 | source=preset/custom 时必填,通过音色列表或创建音色接口取得 |
| voice.asset_id | String | 条件必填 | source=asset 时必填,通过登记参考音频素材接口取得 |
音色列表不按模型区分。使用 preset/custom 时传 voice_id,使用 asset 时传 asset_id。以下示例中的 ID 均需替换为接口实际返回值。
curl 'https://cp.compshare.cn/audio/v1/voices?kind=preset' \
-H 'Authorization: Bearer <YOUR_API_KEY>'预设音色示例
curl -X POST 'https://cp.compshare.cn/audio/v1/speech/jobs' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: indextts2-preset-001' \
-d '{
"model": "indextts2",
"text": "你好,欢迎使用优云智算。",
"language": "ZH",
"voice": {"source": "preset", "voice_id": "<PRESET_VOICE_ID>"},
"speed": 1.0,
"auto_emotion": true
}'生成英文时使用 language="EN" 并填写英文正文。
自定义音色与读音示例
curl -X POST 'https://cp.compshare.cn/audio/v1/speech/jobs' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: indextts2-custom-001' \
-d '{
"model": "indextts2",
"text": "欢迎来到重庆,通过API了解这座城市。",
"language": "ZH",
"voice": {"source": "custom", "voice_id": "<CUSTOM_VOICE_ID>"},
"speed": 0.9,
"auto_emotion": false,
"emotion_description": "温柔、自然,像朋友在介绍自己的家乡",
"emotion_strength": 0.8,
"pronunciations": [
{"word": "重庆", "kind": "pinyin", "value": "chong2 qing4"},
{"word": "API", "kind": "alias", "value": "诶屁爱"}
]
}'手动情绪向量
情绪向量固定为 8 维,顺序为:高兴、愤怒、悲伤、恐惧、厌恶、低落、惊讶、平静。
- 每个元素必须是
0~0.8的数值,不能为null;元素之和必须大于0且不超过0.8。 - 必须显式设置
auto_emotion=false,并省略emotion_description或传空字符串。 single必须恰好有一个非零元素;mixed支持组合情绪。- 省略
emotion_vector_mode时,一个非零元素按single处理,否则按mixed处理。 emotion_strength单独控制强度,无需预先乘进向量。
例如,在创建请求中加入:
{
"auto_emotion": false,
"emotion_vector": [0.4, 0, 0, 0, 0, 0, 0, 0.2],
"emotion_vector_mode": "mixed",
"emotion_strength": 0.8
}auto_emotion=false 且没有情绪描述和向量时,使用参考音色本身的表现进行生成。
读音规则
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| pronunciations[].word | String | 是 | 正文中的目标词语,去除首尾空白后为 1~64 个字符;同一请求中不能重复 |
| pronunciations[].kind | String | 是 | 仅支持 pinyin 或 alias |
| pronunciations[].value | String | 是 | 指定读音,去除首尾空白后为 1~512 个字符 |
| kind | 用途 | 示例 |
|---|---|---|
pinyin | 中文拼音;目标词须为汉字,拼音音节数量与汉字数量一致,每个音节需带声调,音节间用空格分隔 | {"word":"重庆","kind":"pinyin","value":"chong2 qing4"} |
alias | 用另一段文字引导目标词的读音 | {"word":"API","kind":"alias","value":"诶屁爱"} |
词语和读音不能包含控制字符或 <、>、|。IndexTTS2 不支持 cmu 或 kana,传入会返回业务错误。读音规则不改变积分计费所依据的原始正文。
响应参数
| 名称 | 类型 | 描述 |
|---|---|---|
| task_id | String | 任务 ID,用于查询、取消和删除任务 |
| billable_characters | Integer / null | 正文计费字符数;无法还原的历史记录为 null,不代表 0 |
| point_cost | Number | 本任务创建时确定的积分费用,最多两位小数 |
| point_status | String | reserved 已预占、consumed 已扣除、released 已释放;新建任务为 reserved,幂等重试返回原任务当前状态 |
{
"task_id": "<TASK_ID>",
"billable_characters": 10,
"point_cost": 0.30,
"point_status": "reserved"
}此例正文为 你好,欢迎使用优云智算。,包含 10 个计费字符,假设每 100 字符 3 积分且 point_precision=2。价格仅为示例,实际以计价接口和任务返回值为准。
查询任务与下载
curl 'https://cp.compshare.cn/audio/v1/speech/jobs/<TASK_ID>' \
-H 'Authorization: Bearer <YOUR_API_KEY>'查询时只需任务 ID,不需要再次传入模型。
{
"task": {
"task_id": "<TASK_ID>",
"model": "indextts2",
"type": "text_to_speech",
"input": {
"text": "你好,欢迎使用优云智算。",
"language": "ZH",
"voice": {"source": "preset", "voice_id": "<PRESET_VOICE_ID>"},
"auto_emotion": true,
"emotion_strength": 0.8,
"speed": 1
},
"status": "succeeded",
"attempt": 1,
"max_attempts": 3,
"billable_characters": 10,
"point_cost": 0.30,
"point_status": "consumed",
"error_message": "",
"output_url": "https://example.com/generated/output.wav",
"output_size": 240000,
"created_at": 1789459200,
"started_at": 1789459203,
"finished_at": 1789459215
}
}task.model 表示实际任务模型;其余字段与 IndexTTS 2.5 的任务响应相同。兼容旧服务时可能不返回 model,未记录模型的历史任务归属 IndexTTS 2.5。
| 状态 | 含义 | 调用方处理 |
|---|---|---|
queued | 排队中 | 继续轮询,或取消任务 |
generating | 生成或上传结果中 | 继续轮询 |
succeeded | 生成成功 | 从 task.output_url 下载 WAV |
failed | 生成失败 | 查看 task.error_message;重新生成需使用新的幂等键 |
cancelled | 已取消 | 停止轮询 |
任务列表返回两种模型的任务,可通过 items[].model 区分;当前不支持按 model 查询筛选。列表分页、状态和时间筛选见查询任务列表。
仅 queued 任务可取消,取消后释放预占积分。删除任务要求任务已结束且积分已结算;删除会移除结果文件,不退回已消费积分。生成结果纳入组织媒体库管理,请及时下载保存。
使用参考音频与保存音色
上传和音色管理接口不需要 model,两种模型可以复用同一素材或音色:
- 调用获取参考音频上传地址,传
file_name、content_type、file_size。 - 向返回的完整
upload_url执行 PUT,上传时Content-Type与申请时一致,无需携带模型 API Key。 - 调用登记参考音频素材,取得
asset_id。 - 使用
voice.source=asset创建 IndexTTS2 任务,或先创建自定义音色取得voice_id。
参考音频支持 WAV、MP3、FLAC、OGG、M4A;默认大小上限为 15 MiB(15728640 字节),登记时 duration_ms 范围为 500~30000 毫秒。文件扩展名和 MIME 类型必须匹配。登记后尚未使用的素材默认保留 7 天,长期复用可保存为自定义音色。
直接使用素材生成,并同时保存自定义音色:
curl -X POST 'https://cp.compshare.cn/audio/v1/speech/jobs' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: indextts2-reference-001' \
-d '{
"model": "indextts2",
"text": "这是使用参考音频生成的语音。",
"language": "ZH",
"voice": {"source": "asset", "asset_id": "<ASSET_ID>"},
"save_voice": true,
"voice_name": "我的旁白音色"
}'创建任务响应返回任务 ID 和计费字段,不返回新音色 ID;保存的音色通过 GET /audio/v1/voices?kind=custom 查询。需要立即取得 voice_id 时,先单独创建自定义音色。
查询语音计价与积分余额
curl 'https://cp.compshare.cn/audio/v1/pricing' \
-H 'Authorization: Bearer <YOUR_API_KEY>'IndexTTS2 与 IndexTTS 2.5 使用相同的语音计价规则,查询不需要 model。响应字段及精度说明见查询语音计价与积分余额。
precision = point_precision(缺失时为 0)
scale = 10 ** precision
积分费用 = ceil(正文计费字符数 × costs.text_to_speech × scale / unit_characters) / scaleenabled=false时不能创建语音任务;创建前确认balance.available_points足够。- 汉字、Unicode 字母和十进制数字计费;空白、标点和其他符号不计费,但仍占用 2000 字符输入限额。
- 情绪描述、读音规则不计入正文计费字符数。
point_precision=0时向上取整到 1 积分,point_precision=2时向上取整到 0.01 积分;整次请求只向上取整一次。- 费用、余额是 JSON 数字,可能包含两位小数,不应限定为整数或字符串。价格和计费字符基数始终以接口返回值为准。
- 创建任务预占积分,成功后扣除,失败或取消后释放。
point_cost是创建时确定的费用,是否实际消费以point_status为准。 - 音频、视频和图片任务共用组织积分余额。
错误处理
鉴权失败返回 HTTP 401;网关参数格式错误返回 HTTP 400;下游连接或响应解析失败返回 HTTP 502。
业务后端错误保留原 HTTP 状态和响应体,常见字段为 RetCode、Message、request_uuid。即使 HTTP 状态为 200,只要 RetCode 非零,也表示请求失败。下游 HTTP 错误也可能返回非 JSON 内容。
| 情况 | 处理建议 |
|---|---|
model 名称错误 | 使用区分大小写的 indextts2 |
使用 JA、ES 或 AR | IndexTTS2 仅支持 ZH、EN;需要其他语言时改用 indextts2.5 并使用新幂等键 |
使用 cmu 或 kana 读音规则 | 改用 pinyin、alias,或切换到 IndexTTS 2.5 |
ClientToken belongs to another Model | 同一幂等键已用于另一模型;新模型任务使用新键 |
| 情绪向量与自动情绪或描述冲突 | 显式传 auto_emotion=false,省略情绪描述或设为空字符串 |
| 积分不足 | 查询可用积分并补充积分 |
| 任务、素材或音色不存在 | 检查 ID、组织归属以及资源是否已删除或清理 |
| 创建请求超时 | 使用原模型、原参数和原 Idempotency-Key 重试 |
完整调用示例
完整 Python 示例使用标准库完成查价格、选择音色、创建任务、轮询和下载,并处理业务错误与小数积分。用于 IndexTTS2 时,将创建任务请求中的 model 改为 indextts2,语言选用 ZH 或 EN:
# 沿用完整示例的 api()、text、voice_id 和每个新任务独立的 idempotency_key。
result = api("POST", "/audio/v1/speech/jobs", {
"model": "indextts2",
"text": text,
"language": "ZH",
"voice": {"source": "preset", "voice_id": voice_id},
"speed": 1.0,
"auto_emotion": True,
}, idempotency_key=idempotency_key)
task_id = result["task_id"]