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-gg | 1041/82311 |
TextToSpeechAsync | 长文本转语音,返回 TaskId | 异步 | ✅ engine: tts-gg | 1041/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。
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 字符串(不是对象),放进请求体时要二次转义。最小写法:
{ "engine": "tts-gg" }对应的最小请求(来自接入指引):
{
"Text": "您好",
"VoiceId": "Kore",
"ExtParam": "{\"engine\":\"tts-gg\"}"
}还要注意两点:
VoiceId直接填 Gemini 音色名(如Kore),不是 MPS 系统音色的s1_…或克隆音色的v1_…。把其它引擎的VoiceId拿来用大概率报"音色不存在"。- 拼错的键不会报错。
ExtParam里写了引擎不认识的键,多数情况被静默忽略,返回一段"能听但不对"的音频。
TTS-GG 引擎主要参数
以下来自《TTS-GG 引擎接入指引》,只在 engine: "tts-gg" 时生效,适用于 TextToSpeech 与 TextToSpeechAsync。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| engine | String | 是 | 固定 tts-gg |
| synExt | Object | 否 | 语音合成扩展参数 |
| synExt.model | String | 否 | 模型,默认 tts-gg-2.5-flash。可选值见模型列表 |
| synExt.format | String | 否 | 音频格式:wav(默认)/ mp3 / pcm / ogg_opus / alaw / mulaw |
| synExt.sampleRate | Integer | 否 | 采样率:8000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000,默认 16000 |
| synExt.engineCustom | Object | 否 | 引擎定制化参数 |
| synExt.engineCustom.prompt | String | 否 | 自定义风格提示词:为整段语音设定上下文、情感基调、表达方式,如 年轻温柔的女声,用粤语朗读 |
扩展参数示例(接入指引原文):
{
"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-flash | gemini-2.5-flash-tts | 默认。低延迟、可控,适合日常高性价比场景 |
tts-gg-2.5-pro | gemini-2.5-pro-tts | 可控性最强,适合播客、有声书、客服等结构化场景 |
tts-gg-3.1-flash-preview | gemini-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 共同决定。官方页每个音色都有试听,先听再选。
返回
| 参数 | 类型 | 说明 |
|---|---|---|
| ErrorCode | Integer | 0 成功 |
| Msg | String | 结果消息 |
| AudioData | String | 音频 base64(未指定 Output.OutputType=URL 时返回) |
| AudioUrl | String | 音频 URL,24 小时内有效 |
| ExtInfo | String | 扩展信息 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。
| 参数 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
| Text | String | 是 | 您好,欢迎收听。 | 待合成文本,≤ 2000 字符 |
| VoiceId | String | 是 | Kore | Gemini 音色名,见可用音色 |
| TextLang | String | 否 | zh | 文本语言,不填自动识别 |
| Output.OutputType | String | 否 | URL | 填 URL 时返回 AudioUrl(24 小时有效)而非 base64 |
| ExtParam | String | 否 | {"engine":"tts-gg", ...} | 引擎与扩展参数(JSON 字符串),见引擎主要参数 |
异步语音合成 TextToSpeechAsync
长文本(有声书章节、整篇解说稿)走异步:下发任务拿 TaskId,再轮询结果。官网:1041/79693。
| 参数 | 类型 | 必填 | 示例 | 说明 |
|---|---|---|---|---|
| Text | String | 是 | 长文本… | 待合成文本,无 2000 字符限制 |
| VoiceId | String | 是 | Charon | Gemini 音色名 |
| TextLang | String | 否 | zh | 文本语言,不填自动探测 |
| ExtParam | String | 否 | {"engine":"tts-gg","synExt":{...}} | 同同步接口 |
| Output | Object | 否 | {"OutputType":"URL"} | 输出形式 |
返回 TaskId 后用 DescribeTextToSpeechAsyncTask(官网:1041/79696)查询:
| 参数 | 类型 | 说明 |
|---|---|---|
| TaskId | String | 必填,任务 ID |
| Status | String | success / fail / processing |
| AudioUrl | String | 合成音频 URL |
| VoiceId | String | 本次使用的音色 ID |
| ExtInfo | String | 扩展信息(如 {"duration":1.00325}) |
ErrorCode 在处理中返回 100,不要当成失败。
调用示例
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())# ② 长文本:下任务后轮询
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 Reference | TC3 签名、公共参数、错误码 |
| API Key 环境变量 | SecretId / SecretKey 的配置方式 |
官网接口地址(腾讯云国际站 · Media AI – Dubbing APIs):各接口链接与作用见文首接口与官网文档;数据结构见 Data Types,公共参数见 Common Params,签名见 Signature v3,错误码见 Error Codes。
Google 官网:Gemini-TTS(模型、音色、提示词与标记标签、语言列表)· Voice options。