跳到内容

TTS-Gemini ​

更新时间

本文整理 MPS 上调用 Google Gemini-TTS 模型族的接口用法。Gemini-TTS 在 MPS 里以引擎代号 tts-gg 接入:接口、鉴权、计费、任务查询、存储全部沿用 MPS 既有的语音合成接口,只在扩展参数 ExtParam 里写 "engine": "tts-gg" 切到 Gemini,再按需带上模型、格式和风格提示词。

与 TTS-ElevenLabs 最大的区别:TTS-GG 暂不支持音色克隆,只能用 Gemini 预置音色(如 Kore、Puck);但它可以用一句自然语言 prompt 控制整段的情绪、口音和语气。

接口与官网文档 ​

以下接口均属于 MPS「Media AI – Dubbing APIs」,官网接口地址统一在腾讯云国际站 Media AI – Dubbing APIs 目录下。

支持 TTS-GG 的接口 ​

接口作用调用方式走 Gemini官网接口地址
TextToSpeech短文本转语音(≤ 2000 字符),直接返回音频同步✅ engine: tts-gg1041/82311
TextToSpeechAsync长文本转语音,返回 TaskId异步✅ engine: tts-gg1041/79693
DescribeTextToSpeechAsyncTask查询异步合成结果(Status / AudioUrl)同步跟随任务1041/79696

同目录的其它接口 ​

接口作用走 Gemini官网接口地址
CloneVoice用参考音频克隆音色❌ 接入指引明确「暂不支持克隆」1041/82312
DesignVoiceAsync / DescribeDesignTask用文字描述设计新音色 / 查询结果⏳ 接入指引未列出1041/79694 / 1041/79598
DescribeVoices筛选可用音色⏳ 接入指引未列出;Gemini 音色直接用官方音色名,见可用音色1041/79695
UpdateVoice / DeleteVoice修改 / 删除克隆或设计的音色⏳ 无克隆音色,通常用不到1041/81214 / 1041/81215
ChangeVoice音色转换⏳ 接入指引未列出1041/83750
SyncDubbing早期合一接口(克隆或合成)⏳ 接入指引未列出1041/77775

✅ = 《TTS-GG 引擎接入指引》明确支持;❌ = 明确不支持;⏳ = 接入指引未提及,是否可切到 Gemini 以实际调用为准。

公共约定:

  • 版本号 2019-06-12;接入域名国际站 mps.intl.tencentcloudapi.com(中国站 mps.tencentcloudapi.com)。
  • 鉴权统一 TC3-HMAC-SHA256(SecretId / SecretKey),签名方法见 Quick Start。
  • 每个接口频率上限 20 次/秒。

怎么选引擎 ​

需求选哪个
用一句话控制情绪、口音、语气(如"用香港粤语说""压低声音")本文(engineCustom.prompt)
需要 48000 采样率或 pcm / ogg_opus 输出本文
必须用指定说话人的声音(克隆/复刻)TTS-ElevenLabs / TTS-MiniMax / TTS-Fishaudio(Gemini 不支持克隆)
需要逐字时间戳做卡拉 OK 字幕TTS-ElevenLabs(接入指引未给出 TTS-GG 的时间戳能力)
要枚举式情绪或场景化播报风格TTS-MiniMax / TTS-Seed
已有视频,要整段换语言或替换说话人AI Dubbing

七个外部引擎的完整横向对比(接口覆盖、情绪机制、音频参数、克隆能力)见 Blog 里的 MPS 七大 TTS 引擎横向对比。

引擎切换:通过 ExtParam 调用外部引擎 ​

MPS 的语音合成接口是引擎无关的:Text、VoiceId、TextLang、Output 这些顶层参数对所有引擎都一样,换引擎不换接口、不换鉴权,只看 ExtParam.engine。

text
TextToSpeech / TextToSpeechAsync
        │
        ├─ ExtParam 不带 engine ─────────► MPS 默认引擎
        ├─ ExtParam.engine = "tts-l1" ──► ElevenLabs(见 TTS-ElevenLabs)
        │
        └─ ExtParam.engine = "tts-gg" ──► Google Gemini-TTS
                 │
                 ├─ synExt.*                MPS 抽象过的参数(model / format / sampleRate)
                 └─ synExt.engineCustom.*   Gemini 专属参数(prompt)

ExtParam 是 JSON 字符串(不是对象),放进请求体时要二次转义。最小写法:

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

对应的最小请求(来自接入指引):

json
{
  "Text": "您好",
  "VoiceId": "Kore",
  "ExtParam": "{\"engine\":\"tts-gg\"}"
}

还要注意两点:

  • VoiceId 直接填 Gemini 音色名(如 Kore),不是 MPS 系统音色的 s1_… 或克隆音色的 v1_…。把其它引擎的 VoiceId 拿来用大概率报"音色不存在"。
  • 拼错的键不会报错。 ExtParam 里写了引擎不认识的键,多数情况被静默忽略,返回一段"能听但不对"的音频。

TTS-GG 引擎主要参数 ​

以下来自《TTS-GG 引擎接入指引》,只在 engine: "tts-gg" 时生效,适用于 TextToSpeech 与 TextToSpeechAsync。

参数类型必填说明
engineString是固定 tts-gg
synExtObject否语音合成扩展参数
synExt.modelString否模型,默认 tts-gg-2.5-flash。可选值见模型列表
synExt.formatString否音频格式:wav(默认)/ mp3 / pcm / ogg_opus / alaw / mulaw
synExt.sampleRateInteger否采样率:8000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000,默认 16000
synExt.engineCustomObject否引擎定制化参数
synExt.engineCustom.promptString否自定义风格提示词:为整段语音设定上下文、情感基调、表达方式,如 年轻温柔的女声,用粤语朗读

扩展参数示例(接入指引原文):

json
{
  "engine": "tts-gg",
  "synExt": {
    "engineCustom": {
      "prompt": "用香港粤语说"
    }
  }
}

与 TTS-L1 对比:TTS-GG 的格式里是 mulaw(TTS-L1 写作 ulaw)、ogg_opus(TTS-L1 写作 opus),字符串按各自引擎原样传;TTS-GG 接入指引没有 speed 参数,语速用 prompt 描述(如"语速稍快")。

TTS-GG 模型列表 ​

模型对应 Gemini 模型说明(据 Google 官方)
tts-gg-2.5-flashgemini-2.5-flash-tts默认。低延迟、可控,适合日常高性价比场景
tts-gg-2.5-progemini-2.5-pro-tts可控性最强,适合播客、有声书、客服等结构化场景
tts-gg-3.1-flash-previewgemini-3.1-flash-tts-preview预览版,低延迟;Google 侧所有音色在该模型上均为 Preview

"对应 Gemini 模型"一列是按命名规则推断的映射,模型说明引自 Google Gemini-TTS 文档。具体哪些模型在你的账号/区域可用,以实际调用返回为准。

可用音色 ​

接入指引指向 Google 官方音色列表:Gemini-TTS · Voice options。截至本文更新共 30 个,VoiceId 直接填名字:

性别音色名
女声(14)Achernar Aoede Autonoe Callirrhoe Despina Erinome Gacrux Kore Laomedeia Leda Pulcherrima Sulafat Vindemiatrix Zephyr
男声(16)Achird Algenib Algieba Alnilam Charon Enceladus Fenrir Iapetus Orus Puck Rasalgethi Sadachbia Sadaltager Schedar Umbriel Zubenelgenubi

Gemini 音色不绑定语言:同一个 Kore 可以读中文、英文、泰语,口音和语言由 TextLang、文本本身和 prompt 共同决定。官方页每个音色都有试听,先听再选。

返回 ​

参数类型说明
ErrorCodeInteger0 成功
MsgString结果消息
AudioDataString音频 base64(未指定 Output.OutputType=URL 时返回)
AudioUrlString音频 URL,24 小时内有效
ExtInfoString扩展信息 JSON 字符串,含 duration(音频时长,秒)

风格提示词 prompt 怎么写 ​

engineCustom.prompt 是 TTS-GG 最有价值的参数。Google 官方把语音控制拆成三个杠杆,三者语义一致时效果最稳:

杠杆作用在 MPS 里对应
风格提示词 Style Prompt决定整段的情绪基调与表达方式synExt.engineCustom.prompt
文本内容 Text词句本身的语义;情绪饱满的文本比中性文本可靠得多Text
标记标签 Markup Tags(Preview)局部插入动作或风格变化,如 [sigh]、[short pause]写在 Text 里 ⏳

写法建议(据 Google 官方):

  • 越具体越稳。 "像 1940 年代的电台新闻播音员" 比 "老派一点" 好;"用被逗乐的方式笑出来" 比只写 [laughing] 好。
  • 文本要配合情绪。 想要"害怕"的语气,我好像听到有人在屋里 比 会议在下午四点 可靠得多。
  • 口音、方言写进 prompt。 如 用香港粤语说、带一点新加坡英语口音。
  • 新 prompt 先试一句。 改了提示词先合成一句话试听,再跑批量。

常用标记标签(Google 官方,均为 Preview):

类型标签效果
非语音声音[sigh] [laughing] [uhm]插入叹气 / 笑声 / 犹豫声,标签本身不读出
风格修饰[sarcasm] [robotic] [shouting] [whispering] [extremely fast]影响后续语句的语气、音量或语速
停顿[short pause] [medium pause] [long pause]约 250ms / 500ms / 1000ms+ 的静音

标记标签需要先实测

《TTS-GG 引擎接入指引》只写了 prompt,没有说明 Text 里的方括号标签是否会原样透传给 Gemini。用标签前先合成一句确认效果 —— 如果被当成普通文本,方括号里的词会被直接读出来。另外 Google 文档提示 [scared] [curious] [bored] 这类形容词标签会被读出来,情绪请优先写在 prompt 里。

同步语音合成 TextToSpeech ​

适合配音单句、短旁白、试听。单次文本不超过 2000 字符,超了返回错误,改用异步接口。官网:1041/82311。

参数类型必填示例说明
TextString是您好,欢迎收听。待合成文本,≤ 2000 字符
VoiceIdString是KoreGemini 音色名,见可用音色
TextLangString否zh文本语言,不填自动识别
Output.OutputTypeString否URL填 URL 时返回 AudioUrl(24 小时有效)而非 base64
ExtParamString否{"engine":"tts-gg", ...}引擎与扩展参数(JSON 字符串),见引擎主要参数

异步语音合成 TextToSpeechAsync ​

长文本(有声书章节、整篇解说稿)走异步:下发任务拿 TaskId,再轮询结果。官网:1041/79693。

参数类型必填示例说明
TextString是长文本…待合成文本,无 2000 字符限制
VoiceIdString是CharonGemini 音色名
TextLangString否zh文本语言,不填自动探测
ExtParamString否{"engine":"tts-gg","synExt":{...}}同同步接口
OutputObject否{"OutputType":"URL"}输出形式

返回 TaskId 后用 DescribeTextToSpeechAsyncTask(官网:1041/79696)查询:

参数类型说明
TaskIdString必填,任务 ID
StatusStringsuccess / fail / processing
AudioUrlString合成音频 URL
VoiceIdString本次使用的音色 ID
ExtInfoString扩展信息(如 {"duration":1.00325})

ErrorCode 在处理中返回 100,不要当成失败。

调用示例 ​

python
import json
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.mps.v20190612 import mps_client, models

cred = credential.Credential("<SecretId>", "<SecretKey>")
http_profile = HttpProfile(endpoint="mps.tencentcloudapi.com")
client = mps_client.MpsClient(cred, "ap-guangzhou", ClientProfile(http_profile=http_profile))

# ① 同步合成:tts-gg + 2.5 Pro + 48k mp3 + 粤语风格提示词
req = models.TextToSpeechRequest()
req.from_json_string(json.dumps({
    "Text": "各位观众,欢迎收看今晚嘅节目。",
    "VoiceId": "Kore",
    "Output": {"OutputType": "URL"},
    "ExtParam": json.dumps({
        "engine": "tts-gg",
        "synExt": {
            "model": "tts-gg-2.5-pro",
            "format": "mp3",
            "sampleRate": 48000,
            "engineCustom": {"prompt": "年轻温柔的女声,用香港粤语,像电视台主持人一样亲切地开场"}
        }
    })
}))
print(client.TextToSpeech(req).to_json_string())
python
# ② 长文本:下任务后轮询
req = models.TextToSpeechAsyncRequest()
req.from_json_string(json.dumps({
    "Text": "<长文本>",
    "TextLang": "zh",
    "VoiceId": "Charon",
    "ExtParam": json.dumps({
        "engine": "tts-gg",
        "synExt": {"engineCustom": {"prompt": "低沉平稳的纪录片旁白语气"}}
    })
}))
task_id = client.TextToSpeechAsync(req).TaskId

q = models.DescribeTextToSpeechAsyncTaskRequest()
q.from_json_string(json.dumps({"TaskId": task_id}))
print(client.DescribeTextToSpeechAsyncTask(q).to_json_string())  # Status / AudioUrl

限制与注意事项 ​

  • 暂不支持音色克隆:需要复刻真人声音请用 TTS-ElevenLabs 的 CloneVoice。
  • 同步接口单次 2000 字符上限;长文一律走 TextToSpeechAsync。
  • Google 侧单次请求另有上限:文本与 prompt 各 ≤ 4000 字节、合计 ≤ 8000 字节,输出音频超过约 655 秒会被截断。中文一个字约 3 字节,长 prompt + 长文本时注意别撞 Google 的上限;MPS 异步接口如何分段以实际返回为准。
  • AudioUrl 有效期 24 小时,要长期保存必须落自己的 COS,不要存 URL 当资产。
  • 单接口 20 次/秒;批量合成请自己做并发控制与重试(ErrorCode=100 是处理中,不是失败)。
  • 语言:Gemini-TTS 官方 GA 语言 24 种(含 th-TH 泰语、vi-VN 越南语、id-ID 印尼语等),中文普通话 cmn-CN 与粤语等在 Google 侧为 Preview;MPS 的 TextLang 仍按 MPS 语言代码传(如 zh),粤语等方言建议同时写进 prompt。
  • 引擎参数拼错不会报错,改参数后先合成一句话试听,别直接跑批量。

相关文档 ​

站内:

文档内容
MPS 七大 TTS 引擎横向对比七个外部引擎的能力、参数与选型对比
TTS-ElevenLabs同一套接口的 ElevenLabs 引擎(tts-l1),支持克隆与字符级时间戳
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 维情感向量
TTS-Seedaudio同一套接口的 Seed Audio 引擎(tts-sa),唯一支持图片参考生成,字级时间戳
AI Dubbing整段视频换语言、说话人替换(ProcessMedia + 配音模板)
MPS API ReferenceTC3 签名、公共参数、错误码
API Key 环境变量SecretId / SecretKey 的配置方式

官网接口地址(腾讯云国际站 · Media AI – Dubbing APIs):各接口链接与作用见文首接口与官网文档;数据结构见 Data Types,公共参数见 Common Params,签名见 Signature v3,错误码见 Error Codes。

Google 官网:Gemini-TTS(模型、音色、提示词与标记标签、语言列表)· Voice options。

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