TTS-Index
本文整理 MPS 上调用 IndexTTS 语音合成的接口用法。IndexTTS 在 MPS 里以引擎代号 index-tts 接入:接口、鉴权、计费、任务查询、存储全部沿用 MPS 既有的语音合成接口,只在扩展参数 ExtParam 里写 "engine": "index-tts" 切到 IndexTTS,再按需带上模型、情感等参数。
index-tts 有三件事跟 MPS 上的其它 TTS 引擎都不一样,也是选它的主要理由:
VoiceId直接填参考音频 URL —— 不是音色名、也不是克隆后的 ID。换句话说,零样本克隆就是它的默认工作方式,没有「先建音色」这一步,也不需要额外参数开启。- 音色与情感可以来自两段不同的音频 ——
VoiceId决定"谁在说",engineCustom.emo_audio_url决定"用什么情绪说",两者独立。这是七个引擎里唯一支持「A 的声音 + B 的情绪」的。 - 情感有 5 条控制路径 —— 参考音频、权重、8 维向量、随机采样、文本描述,可以按精度需求挑一条,是七个引擎里情感控制最细的。
建议走异步接口
《IndexTTS 引擎接入指引》明确提示:IndexTTS 引擎耗时较久,建议使用异步接口。七个引擎里只有它和 tts-sa 的接入指引写了这句 —— 同步 TextToSpeech 虽然可用,但长文本容易触发超时,生产链路优先用 TextToSpeechAsync + 轮询。
和另外五个引擎怎么选
七个引擎的完整横向对比(接口覆盖、情绪机制、音频参数、克隆能力)见 Blog 里的 MPS 七大 TTS 引擎横向对比。 一句话版本:要免建音色、直接拿一段音频就克隆,或要音色与情感分别取样 → 本文。
接口与官网文档
以下接口均属于 MPS「Media AI – Dubbing APIs」,官网接口地址统一在腾讯云国际站 Media AI – Dubbing APIs 目录下。
支持 index-tts 的接口
《IndexTTS 引擎接入指引》列出以下 3 个接口可通过 ExtParam.engine 切到 IndexTTS:
| 接口 | 作用 | 调用方式 | 官网接口地址 |
|---|---|---|---|
TextToSpeech | 短文本转语音,直接返回音频 | 同步 | 1041/82311 |
TextToSpeechAsync | 长文本转语音,返回 TaskId(推荐) | 异步 | 1041/79693 |
DescribeTextToSpeechAsyncTask | 查询异步合成结果(Status / AudioUrl) | 同步 | 1041/79696 |
同目录的其它接口
| 接口 | 作用 | 走 index-tts | 官网接口地址 |
|---|---|---|---|
DescribeVoices | 查询可用音色 | ⏳ 接入指引未列出 | 1041/79695 |
CloneVoice | 用参考音频克隆音色,得到可复用的 VoiceId | ⏳ 接入指引未列出 | 1041/82312 |
DesignVoiceAsync / DescribeDesignTask | 用文字描述设计新音色 / 查询结果 | ⏳ 接入指引未列出 | 1041/79694 / 1041/79598 |
UpdateVoice / DeleteVoice | 修改 / 删除克隆或设计的音色 | ⏳ 接入指引未列出 | 1041/81214 / 1041/81215 |
ChangeVoice | 音色转换 | ⏳ 接入指引未列出 | 1041/83750 |
SyncDubbing | 早期合一接口(克隆或合成) | ⏳ 接入指引未列出 | 1041/77775 |
⏳ = 接入指引未提及,是否可切到 IndexTTS 以实际调用为准。
没列 DescribeVoices 与 CloneVoice,但这是自洽的
index-tts 的接入指引是六篇里最短的,只列了 3 个接口 —— 比 tts-f 还少了 CloneVoice。 不过这两个缺口对它影响很小:VoiceId 填的就是参考音频 URL,既不需要先用 DescribeVoices 枚举系统音色,也不需要先用 CloneVoice 换一个 ID。要复用音色,把那条音频 URL 存在自己业务侧即可。
公共约定:
- 版本号
2019-06-12;接入域名国际站mps.intl.tencentcloudapi.com(中国站mps.tencentcloudapi.com)。 - 鉴权统一 TC3-HMAC-SHA256(SecretId / SecretKey),签名方法见 Quick Start。
- 每个接口频率上限
20 次/秒。
与其它引擎的能力对比
MPS 上目前有七个外部 TTS 引擎。完整的横向对比(接口覆盖、情绪机制、音频参数、克隆能力、选型建议)见 Blog 里的 MPS 七大 TTS 引擎横向对比 —— 对比表只在那一篇维护,避免各篇口径不一致。
index-tts 在其中的位置:唯一把参考音频直接写进 VoiceId 的引擎,也是唯一能把音色与情感分别取样的;代价是接入指引未列出任何归一化音频参数(格式、采样率、语速、音量都没提)。
引擎切换:ExtParam.engine
MPS 的语音合成接口本身不分引擎,靠 ExtParam 这个 JSON 字符串字段决定由哪个引擎执行。index-tts 用到三层:
| 层级 | 作用 | 说明 |
|---|---|---|
engine | 选引擎 | 本文固定填 index-tts |
synExt.* | MPS 归一化后的合成参数 | 接入指引只列出了 model |
synExt.engineCustom.* | 透传给 IndexTTS 原厂的参数 | 情感音频、情感向量、情感文本(仅 2.0+ 模型) |
ExtParam 在请求里是字符串,不是对象 —— JSON 需要转义后作为字符串传入(见调用示例)。
接入指引没列 format / sampleRate / speed / vol / duration
另外五个引擎的接入指引都给了一组 synExt 归一化音频参数,index-tts 的只给了 model。也就是说音频格式、采样率、语速、音量、指定时长这几项是否生效无从查证,要用先实测。 别照着 tts-f 或 tts-s 的参数表直接套 —— 那是另一个引擎的声明范围,不构成本引擎的依据。
index-tts 主要参数
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
engine | String | 是 | 填 index-tts |
synExt | Object | 否 | 语音合成扩展参数 |
synExt.model | String | 否 | 指定模型,支持 index-tts-2(默认)、index-tts-1.5 |
synExt.engineCustom | Object | 否 | 引擎客制化参数,透传 IndexTTS 原厂请求参数。仅 2.0+ 模型支持 |
模型参数名以实际调用为准
接入指引的参数表把"指定模型"那一行的参数名也写作 synExt(与上一行的对象本身同名,类型却是 String)。同一个字段不可能既是 Object 又是 String,按上下文与其它五个引擎的命名惯例,本文记为 synExt.model。若调用报参数错误,请按原文写法 synExt 重试。
模型列表
| 取值 | 说明 | 支持 engineCustom |
|---|---|---|
index-tts-2 | 默认模型,2.0 代际 | ✅ |
index-tts-1.5 | 上一代模型 | ❌ 低于 2.0 |
情感能力绑定模型版本
engineCustom 下的全部情感参数仅 2.0+ 模型支持。显式把 model 指定成 index-tts-1.5 的同时又传情感参数,情感那部分不会生效 —— 不指定 model 走默认的 index-tts-2 反而是安全的。
engineCustom 参数
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
emo_audio_url | String | 否 | 情感参考音频 URL —— 从这段音频里取"情绪",与 VoiceId 取的"音色"相互独立 |
emo_alpha | Float | 否 | 情感参考音频权重 |
emo_vector | Array of Float | 否 | 8 维情感向量,顺序为 [高兴, 愤怒, 悲伤, 害怕, 厌恶, 忧郁, 惊讶, 平静],示例 [0, 0, 0.8, 0, 0, 0, 0, 0] |
use_random | Bool | 否 | 开启随机情感采样,默认 false |
use_emo_text | Bool | 否 | 根据文本自动生成情感向量 |
emo_text | String | 否 | 直接给一段情感描述文本,自动转换为情感向量。注意这不是要合成的正文 |
emo_alpha 未给取值范围
接入指引只说 emo_alpha 是"情感参考音频权重",没有给取值区间与默认值。按"权重"的常规语义大概是 [0, 1],但这只是推测 —— 要调这个值请先用短文本试几档确认边界,别直接按 1.0 以上的值跑批量。
参数示例
一份完整的 ExtParam 对象(展开后便于阅读,实际传参需转义为字符串):
{
"engine": "index-tts",
"synExt": {
"engineCustom": {
"emo_text": "你吓死我了!你是鬼吗?"
}
}
}这里的 emo_text 是情感描述,不是要合成的文本 —— 要念的内容在请求的 Text 字段里。
接入指引示例里带了 JSON 注释,照抄会解析失败
接入指引的这段示例在 emo_text 后面跟了一个 // 情感描述,非合成文本 的行内注释。标准 JSON 不允许注释,直接复制会被判为参数错误。本文已移除注释,改用正文说明同一件事。
情感控制的五条路径
index-tts 的情感不是一个枚举值,而是五种互为替代的输入方式。按可控性从高到低排:
| 路径 | 参数 | 精度 | 适合 |
|---|---|---|---|
| 8 维向量 | emo_vector | 最高,逐维连续可调 | 批量生产,需要可复现、可微调 |
| 情感参考音频 | emo_audio_url + emo_alpha | 高,但取决于样本 | 已有目标情绪的样音,想"照着这个语气念" |
| 情感描述文本 | emo_text(配 use_emo_text) | 中,自然语言描述 | 快速试效果,不想调数值 |
| 随机采样 | use_random | 低,不可复现 | 要多样性(如同一句话生成多个版本) |
| 不传 | — | — | 跟随 VoiceId 参考音频本身的情绪 |
8 维向量怎么填
八个维度依次是 [高兴, 愤怒, 悲伤, 害怕, 厌恶, 忧郁, 惊讶, 平静]。接入指引的示例 [0, 0, 0.8, 0, 0, 0, 0, 0] 是把第 3 维(悲伤)给到 0.8、其余留 0 —— 即单一情绪定向。 混合情绪理论上可以多维同时给值,但接入指引没有说明是否需要归一化(各维之和是否必须为 1),这属于未声明行为,混合前先实测。
use_emo_text 与 emo_text 的关系未明确
表里 use_emo_text("根据文本自动生成情感向量")与 emo_text("直接提供特定的文本情感描述")是两个独立参数,但接入指引没有说明只传 emo_text 时是否要同时把 use_emo_text 置 true。 参数表的示例只传了 emo_text,本文按此记录;若情感未生效,补一个 "use_emo_text": true 再试。
多条路径同时传会怎样
接入指引没有给情感路径之间的优先级。安全做法是一次只用一条 —— 想要精确可复现就用 emo_vector,想要照着样音就用 emo_audio_url,不要同时传。
音色(VoiceId)
这是 index-tts 与其它五个引擎最大的差异:
| 引擎 | VoiceId 填什么 |
|---|---|
index-tts | 参考音频 URL,例如 https://example.com/narration_voice_zh.wav |
tts-s / tts-gg | 系统音色名(DescribeVoices 查询) |
tts-l1 / minimax / tts-f | 系统音色名,或 CloneVoice 返回的音色 ID |
也就是说 index-tts 没有"音色列表"这个概念 —— 每次请求带一段参考音频,当次就按这个音色合成。
这种设计省了什么、代价是什么
省了:音色的创建、存储、生命周期管理全都不需要,DescribeVoices 与 CloneVoice 这两步直接跳过。特别适合 UGC 场景(一人一音色、用完即弃),或音色数量远大于复用次数的批量任务。 代价是:同一个音色要用成千上万次时,每次请求都要让服务端重新拉取并处理这段参考音频 —— 既多一次网络往返,也要保证那个 URL 长期可访问。参考音频托管在自己的 CDN 或 COS 上,别用会过期的临时链接。
参考音频的格式与时长要求未声明
接入指引只说"VoiceId 参数填参考音频 URL",示例是一个 .wav,没有给格式白名单、时长建议或文件大小上限。 tts-f 的接入指引对参考音频给过"10–30 秒清晰人声、尽量减少背景噪音"的建议,可以作为经验值参考,但那是 Fish Audio 的声明、不是 IndexTTS 的,不要当作本引擎的依据。实际要求请以调用结果为准。
输出扩展信息 ExtInfo
合成结果的 ExtInfo 是一个 JSON 字符串,解析后目前只有一个字段:
| 参数 | 类型 | 描述 |
|---|---|---|
duration | Float | 语音时长,单位秒 |
例如 {"duration":1.00325}。需要按时长对齐字幕或拼接音轨时从这里取。
没有字符级时间戳
index-tts 只给整段时长,不提供逐字 / 逐句的时间戳。要做卡拉 OK 式的逐字对齐,用 TTS-ElevenLabs 的 with_timestamps。
调用示例
语音合成 TextToSpeech
{
"Text": "您好",
"VoiceId": "https://example.cos-internal.ap-nanjing.tencentcos.cn/common/reel/test/narration_voice_zh.wav",
"ExtParam": "{\"engine\":\"index-tts\"}"
}VoiceId 填的是参考音频 URL,不是音色名;ExtParam 的值是转义后的 JSON 字符串,不是嵌套对象。
这是最小可用请求
不传 model(走默认 index-tts-2)、不传任何情感参数时,输出就跟随参考音频本身的音色与情绪。先用这个形态验证链路通不通,再逐步加情感参数。
带情感描述文本
{
"Text": "你是什么时候进来的?",
"VoiceId": "https://example.com/narration_voice_zh.wav",
"ExtParam": "{\"engine\":\"index-tts\",\"synExt\":{\"engineCustom\":{\"emo_text\":\"你吓死我了!你是鬼吗?\"}}}"
}注意 Text 与 emo_text 是两段不同的内容:Text 是要念出来的正文,emo_text 只用来推导情绪。
用 8 维向量精确指定情绪
{
"Text": "他再也没有回来。",
"VoiceId": "https://example.com/narration_voice_zh.wav",
"ExtParam": "{\"engine\":\"index-tts\",\"synExt\":{\"engineCustom\":{\"emo_vector\":[0,0,0.8,0,0,0,0,0]}}}"
}第 3 维是"悲伤",给到 0.8,其余留 0。
音色与情感分别取样
{
"Text": "恭喜你,通过了。",
"VoiceId": "https://example.com/speaker_a.wav",
"ExtParam": "{\"engine\":\"index-tts\",\"synExt\":{\"engineCustom\":{\"emo_audio_url\":\"https://example.com/happy_sample.wav\",\"emo_alpha\":0.8}}}"
}音色来自 speaker_a.wav,情绪来自 happy_sample.wav —— 这是 index-tts 独有的组合方式。
异步合成与查询(推荐)
长文本用 TextToSpeechAsync 提交,ExtParam 写法与同步接口完全一致,返回 TaskId;再用 DescribeTextToSpeechAsyncTask 轮询 Status,完成后从 AudioUrl 取音频。
由于 IndexTTS 耗时较久,生产链路建议默认走异步,同步接口只用于短文本试调。
限制与注意事项
VoiceId填参考音频 URL,不是音色名 —— 这是与其它五个引擎最大的差异,封装层要专门处理。- 参考音频 URL 必须长期可访问:每次请求都会重新拉取,别用会过期的临时签名链接。
- 建议走异步接口:接入指引明确提示 IndexTTS 耗时较久,长文本用同步接口容易超时。
- 情感参数仅 2.0+ 模型支持:显式指定
index-tts-1.5时engineCustom下的情感参数不生效。 emo_text不是合成正文:它只用于推导情绪,要念的内容在Text里 —— 搞混会把情感描述念出来。ExtParam是字符串:请求里必须是转义后的 JSON 字符串,直接塞对象会被判为参数错误。- 示例里的 JSON 注释要去掉:接入指引原文的示例带
//注释,标准 JSON 不允许,照抄会解析失败。 emo_alpha没有声明取值范围:接入指引未给区间与默认值,调之前先小范围实测。- 未列出
format/sampleRate/speed/vol/duration:接入指引只给了model一个归一化参数,其它音频参数是否生效以实际调用为准。 - 8 维向量的归一化规则未声明:混合多维情绪前先实测,不确定各维之和是否必须为 1。
- ⏳ 标记的接口以实际调用为准:本文的 ✅ / ⏳ 依据《IndexTTS 引擎接入指引》的列举范围,未列出的接口(含
DescribeVoices、CloneVoice)不代表一定不可用。
相关文档
| 文档 | 说明 |
|---|---|
| MPS 七大 TTS 引擎横向对比 | 七个外部引擎的能力、参数与选型对比 |
| AI 配音 | MPS 配音能力总览与内置引擎 |
| TTS-ElevenLabs | 同一套接口的 ElevenLabs 引擎(tts-l1),支持字符级时间戳 |
| TTS-Gemini | 同一套接口的 Google Gemini-TTS 引擎(tts-gg),用 prompt 控制风格 |
| TTS-MiniMax | 同一套接口的 MiniMax 引擎(minimax),支持克隆与音色设计 |
| TTS-Seed | 同一套接口的 TTS-Seed 引擎(tts-s),24 种情绪枚举 |
| TTS-Fishaudio | 同一套接口的 Fish Audio 引擎(tts-f),内联情绪标签与零样本克隆 |
| TTS-Seedaudio | 同一套接口的 Seed Audio 引擎(tts-sa),唯一支持图片参考生成,字级时间戳 |
| Quick Start | 鉴权与签名方法 |
| Media AI – Dubbing APIs | 官网接口目录 |