跳到内容

TTS-Seedaudio ​

更新时间

本文整理 MPS 上调用 Seed Audio 语音合成的接口用法。Seed Audio 在 MPS 里以引擎代号 tts-sa 接入:接口、鉴权、计费、任务查询、存储全部沿用 MPS 既有的语音合成接口,只在扩展参数 ExtParam 里写 "engine": "tts-sa" 切到 Seed Audio,再按需带上格式、语速、参考资源等参数。

tts-sa 有三件事跟 MPS 上的其它 TTS 引擎都不一样,也是选它的主要理由:

  1. 支持用图片生成语音 —— references 里传一张参考图片,引擎按 text_prompt 的文本内容出语音。七个引擎里只有它能这么做,也是唯一一个输入端跳出「文本 + 音频」范畴的引擎。
  2. 一次请求可以引用多条参考音频,并在文本里点名用哪一条 —— 最多 3 条音频,在 text_prompt 里用 @音频1、@音频2 指定,上传顺序与编号严格对应。其它引擎的参考音频都是「整次请求一个音色」。
  3. 字级时间戳是一个开关,不是模型能力 —— 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 字符串(不是对象),顶层结构固定为:

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 统一抽象层) ​

参数类型必填说明
modelString否当前仅支持 tts-sa-v1
formatString否wav(默认)/ mp3 / pcm / ogg_opus
sampleRateInteger否8000 / 16000 / 24000 / 32000 / 44100 / 48000,默认 16000。ogg_opus 仅支持 48000
speedFloat否语速,[0.5, 2],默认 1.0
volFloat否音量,[0.5, 2.0],0.5 为半倍音量、2.0 为两倍音量,默认不调整
pitchInteger否音调,[-12, 12],值越大音调越高
engineCustomObject否引擎客制化参数,透传原厂请求参数

它的 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 是一个数组(示例里写作 [{...}]),决定这次请求的生成模式。数组里每个元素的可用字段:

参数类型必填说明
speakerString否音色 ID
audio_dataString否参考音频的 Base64 编码
audio_urlString否参考音频 URL,支持远端音频
image_dataString否参考图片的 Base64 编码
image_urlString否参考图片 URL

这五个字段互斥,一个元素只能传一个

接入指引原文:「speaker、audio_data、audio_url、image_data、image_url 参数互斥,仅需传入其中一个参数」。 要同时用多条音频,就在数组里放多个元素,每个元素各带一个 audio_url(或 audio_data)。

参考资源的数量与规格限制:

类型数量上限单条限制支持格式
参考音频最多 3 条时长 ≤ 30 秒,大小 ≤ 10 MBwav / mp3 / pcm / ogg_opus
参考图片最多 1 张大小 ≤ 10 MBjpeg / png / webp

engineCustom.audio_config(输出配置) ​

参数类型必填说明
enable_subtitleBool否启用字幕服务,默认 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 的请求还能正常出音频,而占位值会直接报参数错误。

调用示例 ​

最小可用请求(纯文本、系统音色) ​

json
{
  "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 的实际返回为准,不要直接照搬。

带参考音频(音频参考生成) ​

json
{
  "engine": "tts-sa",
  "synExt": {
    "format": "mp3",
    "speed": 0.9,
    "engineCustom": {
      "references": [
        { "audio_url": "https://example.com/ref.wav" }
      ]
    }
  }
}

传了 references 后外层 VoiceId 不生效,实际音色以 ref.wav 为准。

多条参考音频(配合 @音频N) ​

json
{
  "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)。

图片参考生成 ​

json
{
  "engine": "tts-sa",
  "synExt": {
    "format": "mp3",
    "engineCustom": {
      "references": [
        { "image_url": "https://example.com/scene.jpg" }
      ]
    }
  }
}

开启字级时间戳 ​

json
{
  "engine": "tts-sa",
  "synExt": {
    "format": "mp3",
    "sampleRate": 24000,
    "engineCustom": {
      "audio_config": {
        "enable_subtitle": true
      }
    }
  }
}

时间戳从返回的 ExtInfo 中读取。

查询系统音色 ​

DescribeVoices 的 ExtParam 只需指定引擎:

json
{
  "engine": "tts-sa"
}

异步合成 ​

长文本或开启了图片 / 多音频参考时,走异步更稳:

  1. TextToSpeechAsync —— 参数与同步接口一致,返回 TaskId。
  2. 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 ReferenceTC3 签名、公共参数、错误码
Media AI – Dubbing APIs官网接口目录

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages