Skip to Content
MiniMax H3 文档API 调用IndexTTS2 语音任务 API

IndexTTS2 文生语音 API

IndexTTS2(IndexTTS-2)支持中文和英文语音生成,可使用平台预设音色、自定义音色或参考音频,并调整语速、情绪和指定词语的读音。输出为 WAV 音频。

通过 /audio/v1/* 异步接口调用:创建任务后取得 task_id,轮询任务状态,成功后从 task.output_url 下载音频。创建请求必须显式指定 "model": "indextts2";省略 model 或传空字符串时使用 IndexTTS 2.5。

模型选择与差异

项目IndexTTS2IndexTTS 2.5
modelindextts2indextts2.5(默认)
languageZH 中文、EN 英文ZH、EN、JA 日文、ES 西班牙语、AR 阿拉伯语
pronunciations[].kindpinyin、aliaspinyin、alias、cmu、kana
正文长度最多 2000 个 Unicode 字符最多 2000 个 Unicode 字符
语速0.5~2.00.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

推荐调用流程

  1. 查询 /audio/v1/pricing,确认 enabled=true 且可用积分足够。
  2. 查询 /audio/v1/voices?kind=preset 或 kind=custom,取得 voice_id。
  3. 创建语音任务,指定 model="indextts2",保存返回的 task_id。
  4. 每隔 3 秒查询任务,直到 succeeded、failed 或 cancelled。
  5. 成功后通过 task.output_url 下载 WAV 文件。

创建文生语音任务

POST https://cp.compshare.cn/audio/v1/speech/jobs

请求参数

名称类型必填描述示例值
modelString是(选择本模型)必须为 indextts2;省略或传空字符串会选择 IndexTTS 2.5indextts2
textString是正文,最多 2000 个 Unicode 字符,包含标点和空白;至少包含一个汉字、字母或数字你好,欢迎使用优云智算。
languageString否ZH 中文或 EN 英文,默认 ZH,区分大小写ZH
voiceObject是音色引用,结构见下表{"source":"preset","voice_id":"<VOICE_ID>"}
speedNumber否语速,范围 0.5~2.0;省略或传 0 时按 1.0 处理1.0
auto_emotionBoolean否自动推断情绪,默认 truetrue
emotion_descriptionString否情绪描述,最多 200 个字符;非空时使用描述引导情绪温柔、平静,适合睡前故事
emotion_strengthNumber否情绪强度,范围 0~1,默认 0.8;显式传 0 时保留零值0.8
emotion_vectorArray of Number否8 维手动情绪向量,约束见下文[0.4,0,0,0,0,0,0,0]
emotion_vector_modeString否single 或 mixed;须与 emotion_vector 一起使用single
pronunciationsArray of Object否读音规则,最多 100 条;仅支持 pinyin、alias[{"word":"重庆","kind":"pinyin","value":"chong2 qing4"}]
save_voiceBoolean否默认 false;仅 voice.source=asset 时可设为 true,同时保存自定义音色false
voice_nameString条件必填save_voice=true 时必填,去除首尾空白后为 1~64 个字符我的旁白音色

音色引用

名称类型必填描述
voice.sourceString是preset 平台预设音色、custom 自定义音色、asset 临时参考素材
voice.voice_idString条件必填source=preset/custom 时必填,通过音色列表或创建音色接口取得
voice.asset_idString条件必填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[].wordString是正文中的目标词语,去除首尾空白后为 1~64 个字符;同一请求中不能重复
pronunciations[].kindString是仅支持 pinyin 或 alias
pronunciations[].valueString是指定读音,去除首尾空白后为 1~512 个字符
kind用途示例
pinyin中文拼音;目标词须为汉字,拼音音节数量与汉字数量一致,每个音节需带声调,音节间用空格分隔{"word":"重庆","kind":"pinyin","value":"chong2 qing4"}
alias用另一段文字引导目标词的读音{"word":"API","kind":"alias","value":"诶屁爱"}

词语和读音不能包含控制字符或 <、>、|。IndexTTS2 不支持 cmu 或 kana,传入会返回业务错误。读音规则不改变积分计费所依据的原始正文。

响应参数

名称类型描述
task_idString任务 ID,用于查询、取消和删除任务
billable_charactersInteger / null正文计费字符数;无法还原的历史记录为 null,不代表 0
point_costNumber本任务创建时确定的积分费用,最多两位小数
point_statusStringreserved 已预占、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,两种模型可以复用同一素材或音色:

  1. 调用获取参考音频上传地址,传 file_name、content_type、file_size。
  2. 向返回的完整 upload_url 执行 PUT,上传时 Content-Type 与申请时一致,无需携带模型 API Key。
  3. 调用登记参考音频素材,取得 asset_id。
  4. 使用 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) / scale
  • enabled=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 或 ARIndexTTS2 仅支持 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"]
Last updated on