TTS-Seedaudio
本文整理 MPS 上调用 Seed Audio 语音合成的接口用法。Seed Audio 在 MPS 里以引擎代号 tts-sa 接入:接口、鉴权、计费、任务查询、存储全部沿用 MPS 既有的语音合成接口,只在扩展参数 ExtParam 里写 "engine": "tts-sa" 切到 Seed Audio,再按需带上格式、语速、参考资源等参数。
tts-sa 有三件事跟 MPS 上的其它 TTS 引擎都不一样,也是选它的主要理由:
- 支持用图片生成语音 ——
references里传一张参考图片,引擎按text_prompt的文本内容出语音。七个引擎里只有它能这么做,也是唯一一个输入端跳出「文本 + 音频」范畴的引擎。 - 一次请求可以引用多条参考音频,并在文本里点名用哪一条 —— 最多 3 条音频,在
text_prompt里用@音频1、@音频2指定,上传顺序与编号严格对应。其它引擎的参考音频都是「整次请求一个音色」。 - 字级时间戳是一个开关,不是模型能力 ——
audio_config.enable_subtitle置true就能在ExtInfo里拿到字级时间戳,默认关闭。此前只有 ElevenLabs 提供时间戳(字符级,靠with_timestamps)。
建议走异步接口
《TTS-SA 引擎接入指引》明确提示:TTS-SA 引擎耗时较久,建议使用异步接口。七个引擎里只有它和 IndexTTS 的接入指引写了这句 —— 同步 TextToSpeech 虽然可用,但长文本容易触发超时,生产链路优先用 TextToSpeechAsync + 轮询。
和另外六个引擎怎么选
七个引擎的完整横向对比(接口覆盖、情绪机制、音频参数、克隆能力)见 Blog 里的 MPS 七大 TTS 引擎横向对比。 一句话版本:要用图片生成语音、要一次引用多条参考音频并在文本里点名,或要字级时间戳(且不需要克隆)→ 本文。
接口与官网文档
以下接口均属于 MPS「Media AI – Dubbing APIs」,官网接口地址统一在腾讯云国际站 Media AI – Dubbing APIs 目录下。
支持 tts-sa 的接口
《TTS-SA 引擎接入指引》列出以下 4 个接口可通过 ExtParam.engine 切到 Seed Audio:
| 接口 | 作用 | 调用方式 | 官网接口地址 |
|---|---|---|---|
TextToSpeech | 短文本转语音,直接返回音频 | 同步 | 1041/82311 |
TextToSpeechAsync | 长文本转语音,返回 TaskId(推荐) | 异步 | 1041/79693 |
DescribeTextToSpeechAsyncTask | 查询异步合成结果(Status / AudioUrl) | 同步 | 1041/79696 |
DescribeVoices | 查询可用系统音色 | 同步 | 1041/79695 |
它把第 4 个接口补回来了
Fish Audio 与 IndexTTS 的接入指引都没列 DescribeVoices,tts-sa 列了 —— 七个引擎里,它和前四个引擎一样拥有完整的「三个合成接口 + 音色查询」公共集。 查询时只需在 ExtParam 里写 {"engine": "tts-sa"},没有其它必填参数。
同目录的其它接口
| 接口 | 作用 | 走 tts-sa | 官网接口地址 |
|---|---|---|---|
CloneVoice | 用参考音频克隆音色,得到可复用的 VoiceId | ❌ 接入指引明确「暂不支持克隆」 | 1041/82312 |
DesignVoiceAsync / DescribeDesignTask | 用文字描述设计新音色 / 查询结果 | ⏳ 接入指引未列出 | 1041/79694 / 1041/79598 |
UpdateVoice / DeleteVoice | 修改 / 删除克隆或设计的音色 | ⏳ 接入指引未列出 | 1041/81214 / 1041/81215 |
ChangeVoice | 音色转换 | ⏳ 接入指引未列出 | 1041/83750 |
SyncDubbing | 早期合一接口(克隆或合成) | ⏳ 接入指引未列出 | 1041/77775 |
⏳ = 接入指引未提及,是否可切到 Seed Audio 以实际调用为准;❌ = 接入指引明确不支持。
「暂不支持克隆」不等于「不能用参考音频」
接入指引开头就写了 ps:暂不支持克隆,指的是没有 CloneVoice 这条建音色的路径 —— 你拿不到一个可复用的克隆 VoiceId。 但它可以用参考音频:engineCustom.references 里传 audio_url 或 audio_data,这次请求就按那段音频的音色生成。效果上接近零样本克隆,区别是每次请求都要重新带上音频,且结果不可作为音色沉淀复用。
引擎切换:ExtParam.engine
MPS 的语音合成接口本身与引擎无关,真正决定由哪个引擎合成的是扩展参数 ExtParam 里的 engine 字段。
ExtParam 是一个 JSON 字符串(不是对象),顶层结构固定为:
{
"engine": "tts-sa",
"synExt": {
"format": "mp3",
"speed": 0.9,
"engineCustom": {}
}
}engine—— 必填,固定写tts-sa。synExt—— 选填,MPS 统一抽象过的合成参数(格式、采样率、语速、音量、音调)。synExt.engineCustom—— 选填,透传给 Seed Audio 原厂的参数,参考资源与字幕开关都在这里。
同名参数外层优先,但 references 是例外
synExt.xxx 会覆盖 synExt.engineCustom.xxx。要用原厂独有参数,只写在 engineCustom 里,不要在两层重复。 唯一的例外是 references:传了它,实际音色以参考资源为准,外层 VoiceId 失效(接入指引原文:「传此参数时上层的 VoiceId 可以 mock 一个」)。tts-f 的 references 也有同样的豁免 —— 七个引擎里只有这两个参数被明文豁免于「外层优先」规则。
tts-sa 主要参数
synExt(MPS 统一抽象层)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | String | 否 | 当前仅支持 tts-sa-v1 |
format | String | 否 | wav(默认)/ mp3 / pcm / ogg_opus |
sampleRate | Integer | 否 | 8000 / 16000 / 24000 / 32000 / 44100 / 48000,默认 16000。ogg_opus 仅支持 48000 |
speed | Float | 否 | 语速,[0.5, 2],默认 1.0 |
vol | Float | 否 | 音量,[0.5, 2.0],0.5 为半倍音量、2.0 为两倍音量,默认不调整 |
pitch | Integer | 否 | 音调,[-12, 12],值越大音调越高 |
engineCustom | Object | 否 | 引擎客制化参数,透传原厂请求参数 |
它的 vol 区间和别家不一样
MiniMax、TTS-Seed、Fish Audio 的 vol 都是 (0, 10],而 tts-sa 是 [0.5, 2.0],语义也不同 —— 它是倍率(0.5 半倍、2.0 两倍),不是 10 档刻度。 跨引擎复用参数时,把 vol: 5 直接套到 tts-sa 上会超出范围被判参数错误。
ogg_opus 与采样率的强约束
选 ogg_opus 时采样率只能是 48000,而默认采样率是 16000 —— 也就是说只写 format: "ogg_opus" 而不改 sampleRate,这组参数本身是冲突的。要用 opus 就必须两个一起写。 另外它的采样率可选值里没有 22050(ElevenLabs、MiniMax、Fish Audio 都有),但有 48000(只有 Gemini、TTS-Seed 和它有)。
engineCustom.references(参考资源)
references 是一个数组(示例里写作 [{...}]),决定这次请求的生成模式。数组里每个元素的可用字段:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
speaker | String | 否 | 音色 ID |
audio_data | String | 否 | 参考音频的 Base64 编码 |
audio_url | String | 否 | 参考音频 URL,支持远端音频 |
image_data | String | 否 | 参考图片的 Base64 编码 |
image_url | String | 否 | 参考图片 URL |
这五个字段互斥,一个元素只能传一个
接入指引原文:「speaker、audio_data、audio_url、image_data、image_url 参数互斥,仅需传入其中一个参数」。 要同时用多条音频,就在数组里放多个元素,每个元素各带一个 audio_url(或 audio_data)。
参考资源的数量与规格限制:
| 类型 | 数量上限 | 单条限制 | 支持格式 |
|---|---|---|---|
| 参考音频 | 最多 3 条 | 时长 ≤ 30 秒,大小 ≤ 10 MB | wav / mp3 / pcm / ogg_opus |
| 参考图片 | 最多 1 张 | 大小 ≤ 10 MB | jpeg / png / webp |
engineCustom.audio_config(输出配置)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
enable_subtitle | Bool | 否 | 启用字幕服务,默认 false。开启后返回字级时间戳,从扩展信息 ExtInfo 中读取 |
要做字幕对齐,这个开关必须显式打开
enable_subtitle 默认是 false,不传就拿不到时间戳,而且输出里不会有任何提示 —— 表现是「字幕功能好像没有」,而不是报错。 拿到的是字级时间戳(ElevenLabs 的 with_timestamps 是字符级)。中文场景下字级通常更好用:字符级会把一个汉字和一个标点同等对待,而字级直接对应可显示的最小单位。
三种生成模式
references 传什么,决定引擎走哪条生成路径。这是 tts-sa 与其它引擎差别最大的地方 —— 其它引擎的「参考音频」只有「克隆这个音色」一个用途,而它是一套多模态输入。
纯文本生成
不传 references,引擎按 text_prompt 里的提示词生成音频。
音频参考生成
传入音频参考(audio_url / audio_data),引擎按参考音频 + text_prompt 的提示词生成音频。此时也支持通过 speaker(音色 ID)指定音色。
图片参考生成
传入图片参考(image_url / image_data),引擎按 text_prompt 里的文本内容生成音频。
图片参考是它独有的能力
七个引擎里只有 tts-sa 接受图片输入。接入指引把三种模式的组合写成:纯文本、文本 + 图片、文本 + 音频。 这条路径已经超出「把文字念出来」的范畴 —— 图片提供的是语音风格或场景的线索,而要念的内容仍在文本里。接入指引没有给出图片内容与语音效果的对应规则,首次使用建议先用几张风格差异明显的图实测,再决定是否纳入生产链路。
text_prompt 不在参数表里
三种模式的说明都围绕 text_prompt,但接入指引的参数表里没有定义这个字段 —— 它既不在 synExt 下,也不在 references 或 audio_config 下。 从上下文看它应是 engineCustom 下与 references 平级的字段(原厂透传参数)。调用前建议先用一个最小请求确认它的实际位置,别直接按本文推断批量上线。 另外,MPS 接口本身的 Text 字段才是要合成的正文。text_prompt 与 Text 的关系接入指引未说明,这是本文最大的一处不确定。
@音频N 的引用顺序
多条参考音频时,上传顺序必须与 text_prompt 中 @音频N 的编号顺序严格对应:第一条音频对应 @音频1,第二条对应 @音频2,以此类推。
顺序错了不会报错,只会出错音色
这是一个位置约定,不是具名引用 —— 引擎靠数组下标匹配编号。如果业务侧用 map 或 set 组装 references(顺序不稳定),@音频1 可能指向另一段音频。 表现是「音色串了」,而不是参数错误,排查成本很高。建议在封装层把 references 固定成有序数组,并在拼 text_prompt 时由同一份数据生成编号。
音色(VoiceId)怎么拿
tts-sa 的音色有两条来源,取决于有没有传 references:
| 场景 | VoiceId 怎么填 | 实际音色来源 |
|---|---|---|
不传 references | 系统音色名(通过 DescribeVoices 查询) | 系统音色 |
传了 references | 可以 mock 一个任意值 | 参考资源(音频 / 图片 / speaker) |
「可以 mock 一个」是接入指引的原话,但别真填垃圾值
原文是「传此参数时上层的 VoiceId 可以 mock 一个,实际音色会以此参数为准」。意思是传了 references 后外层 VoiceId 不生效,所以填什么都不影响结果。 实践上建议填一个真实存在的系统音色名而不是 "x" 这种占位值:一旦 references 因为音频拉取失败而未生效,有合法 VoiceId 的请求还能正常出音频,而占位值会直接报参数错误。
调用示例
最小可用请求(纯文本、系统音色)
{
"Text": "您好",
"VoiceId": "zh_female_vv_uranus_bigtts",
"ExtParam": "{\"engine\":\"tts-sa\",\"synExt\":{\"format\":\"mp3\",\"speed\":0.9}}"
}源文档示例里的 engine 值带了前导空格
接入指引的语音合成示例写作 \"engine\":\" tts-sa\"(tts-sa 前有一个空格)。engine 是精确匹配的,带空格会被判参数错误 —— 本文已按正确值 "tts-sa" 写出。 同一处示例的 VoiceId 用的是 zh_female_vv_uranus_bigtts,这其实是 TTS-Seed(tts-s)的音色名。tts-sa 的系统音色请以 DescribeVoices 的实际返回为准,不要直接照搬。
带参考音频(音频参考生成)
{
"engine": "tts-sa",
"synExt": {
"format": "mp3",
"speed": 0.9,
"engineCustom": {
"references": [
{ "audio_url": "https://example.com/ref.wav" }
]
}
}
}传了 references 后外层 VoiceId 不生效,实际音色以 ref.wav 为准。
多条参考音频(配合 @音频N)
{
"engine": "tts-sa",
"synExt": {
"format": "mp3",
"engineCustom": {
"references": [
{ "audio_url": "https://example.com/speaker_a.wav" },
{ "audio_url": "https://example.com/speaker_b.wav" }
]
}
}
}数组第一条对应 @音频1(speaker_a.wav),第二条对应 @音频2(speaker_b.wav)。
图片参考生成
{
"engine": "tts-sa",
"synExt": {
"format": "mp3",
"engineCustom": {
"references": [
{ "image_url": "https://example.com/scene.jpg" }
]
}
}
}开启字级时间戳
{
"engine": "tts-sa",
"synExt": {
"format": "mp3",
"sampleRate": 24000,
"engineCustom": {
"audio_config": {
"enable_subtitle": true
}
}
}
}时间戳从返回的 ExtInfo 中读取。
查询系统音色
DescribeVoices 的 ExtParam 只需指定引擎:
{
"engine": "tts-sa"
}异步合成
长文本或开启了图片 / 多音频参考时,走异步更稳:
TextToSpeechAsync—— 参数与同步接口一致,返回TaskId。DescribeTextToSpeechAsyncTask—— 用TaskId轮询,Status为成功后取AudioUrl。
限制与注意事项
engine精确匹配tts-sa,前后不要带空格(接入指引示例有笔误,见上文)。ExtParam是字符串,必须转义成 JSON 字符串传入,直接塞对象会被判参数错误。- 暂不支持克隆:没有
CloneVoice路径,拿不到可复用的克隆VoiceId。要音色沉淀复用,用 ElevenLabs、MiniMax 或 Fish Audio。 references让外层VoiceId失效,这是「外层优先」规则的明文例外。- 参考音频每条 ≤ 30 秒 / ≤ 10 MB,最多 3 条;参考图片 ≤ 10 MB,最多 1 张。超限行为接入指引未说明。
ogg_opus必须配sampleRate: 48000,只改 format 不改采样率是一组冲突参数。vol是倍率[0.5, 2.0],不是别家的(0, 10]刻度。- 字级时间戳默认关闭,不传
enable_subtitle拿不到时间戳且无提示。 @音频N靠上传顺序匹配,顺序乱了会静默出错音色。- 建议走异步接口:接入指引明确提示耗时较久。
- 情绪与风格没有独立参数:七个引擎里只有它和 ElevenLabs 没有
emotion之类的字段。tts-sa的风格线索来自参考资源与text_prompt,不是枚举值。 text_prompt未在参数表中定义,且与 MPS 的Text字段的关系未说明 —— 上线前务必实测确认。
相关文档
| 文档 | 说明 |
|---|---|
| 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-Index | 同一套接口的 IndexTTS 引擎(index-tts),VoiceId 直填参考音频 URL,8 维情感向量 |
| MPS API Reference | TC3 签名、公共参数、错误码 |
| Media AI – Dubbing APIs | 官网接口目录 |