TTS-Gemini β
This page documents how to call the Google Gemini-TTS model family on MPS. Gemini-TTS is exposed as engine code tts-gg: the APIs, authentication, billing, task polling, and storage are all the standard MPS speech-synthesis APIs β you switch to Gemini only by writing "engine": "tts-gg" inside the extended parameter ExtParam, then add model, format, and style prompt as needed.
The key difference from TTS-ElevenLabs: TTS-GG does not support voice cloning yet β you use Gemini's prebuilt voices (e.g. Kore, Puck). In exchange, a single natural-language prompt controls emotion, accent, and delivery for the whole segment.
APIs and official references β
All of these belong to MPS "Media AI β Dubbing APIs". The official API references live under the Tencent Cloud international site directory Media AI β Dubbing APIs.
APIs that support TTS-GG β
| API | What it does | Mode | Via Gemini | Official reference |
|---|---|---|---|---|
TextToSpeech | Short text to speech (β€ 2000 chars), returns audio directly | sync | β
engine: tts-gg | 1041/82311 |
TextToSpeechAsync | Long text to speech, returns TaskId | async | β
engine: tts-gg | 1041/79693 |
DescribeTextToSpeechAsyncTask | Fetch the async synthesis result (Status / AudioUrl) | sync | follows the task | 1041/79696 |
Other APIs in the same directory β
| API | What it does | Via Gemini | Official reference |
|---|---|---|---|
CloneVoice | Clone a voice from reference audio | β the guide states cloning is not supported yet | 1041/82312 |
DesignVoiceAsync / DescribeDesignTask | Design a voice from a text description / fetch the result | β³ not covered by the guide | 1041/79694 / 1041/79598 |
DescribeVoices | Filter available voices | β³ not covered by the guide; Gemini voices use their official names, see Available voices | 1041/79695 |
UpdateVoice / DeleteVoice | Edit / delete cloned or designed voices | β³ no cloned voices, rarely needed | 1041/81214 / 1041/81215 |
ChangeVoice | Voice conversion | β³ not covered by the guide | 1041/83750 |
SyncDubbing | Earlier all-in-one API (clone or synthesize) | β³ not covered by the guide | 1041/77775 |
β = explicitly supported by the TTS-GG engine integration guide; β = explicitly unsupported; β³ = not mentioned in the guide β whether it routes to Gemini is determined by a live call.
Shared conventions:
- Version
2019-06-12; endpointmps.intl.tencentcloudapi.comon the international site (mps.tencentcloudapi.comon the China site). - Authentication is TC3-HMAC-SHA256 (SecretId / SecretKey); see Quick Start for signing.
- Rate limit is
20 requests/secondper API.
Choosing an engine β
| Need | Use |
|---|---|
| One sentence to steer emotion, accent, and tone (e.g. "speak in Hong Kong Cantonese", "lower your voice") | This page (engineCustom.prompt) |
48000 Hz sample rate or pcm / ogg_opus output | This page |
| A specific speaker's voice (cloning) | TTS-ElevenLabs / TTS-MiniMax / TTS-Fishaudio (Gemini has no cloning) |
| Per-character timestamps for karaoke subtitles | TTS-ElevenLabs (the guide does not document timestamps for TTS-GG) |
| Enumerated emotions or scenario broadcast styles | TTS-MiniMax / TTS-Seed |
| You have a video and need a full language swap or speaker replacement | AI Dubbing |
A full side-by-side comparison of all seven external engines (API coverage, emotion mechanism, audio parameters, cloning) is on the Blog: MPS TTS Engines Compared.
Engine switching: calling an external engine through ExtParam β
The MPS speech-synthesis APIs are engine-agnostic: top-level parameters such as Text, VoiceId, TextLang, and Output are identical for every engine. Switching engines changes neither the API nor the authentication β only ExtParam.engine decides.
TextToSpeech / TextToSpeechAsync
β
ββ ExtParam without engine ββββββΊ MPS default engine
ββ ExtParam.engine = "tts-l1" βββΊ ElevenLabs (see TTS-ElevenLabs)
β
ββ ExtParam.engine = "tts-gg" βββΊ Google Gemini-TTS
β
ββ synExt.* parameters MPS has abstracted (model / format / sampleRate)
ββ synExt.engineCustom.* Gemini-specific parameters (prompt)ExtParam is a JSON string (not an object), so it must be escaped a second time inside the request body. Minimum form:
{ "engine": "tts-gg" }The matching minimum request (from the integration guide):
{
"Text": "ζ¨ε₯½",
"VoiceId": "Kore",
"ExtParam": "{\"engine\":\"tts-gg\"}"
}Two more things to keep in mind:
VoiceIdis the Gemini voice name (e.g.Kore) β not an MPS system voices1_β¦or a clonedv1_β¦. Reusing another engine'sVoiceIdwill most likely fail with "voice not found".- Misspelled keys do not error. Keys the engine does not recognize inside
ExtParamare usually ignored silently, and you get audible-but-wrong audio.
TTS-GG engine parameters β
From the TTS-GG engine integration guide. These apply only when engine is tts-gg, to both TextToSpeech and TextToSpeechAsync.
| Parameter | Type | Required | Notes |
|---|---|---|---|
| engine | String | yes | tts-gg |
| synExt | Object | no | Speech-synthesis extension parameters |
| synExt.model | String | no | Model, default tts-gg-2.5-flash. See model list |
| synExt.format | String | no | Audio format: wav (default) / mp3 / pcm / ogg_opus / alaw / mulaw |
| synExt.sampleRate | Integer | no | Sample rate: 8000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000, default 16000 |
| synExt.engineCustom | Object | no | Engine-specific parameters |
| synExt.engineCustom.prompt | String | no | Custom style prompt: sets context, emotional tone, and delivery for the whole segment, e.g. A young, gentle female voice reading in Cantonese |
Extended-parameter example (verbatim from the guide):
{
"engine": "tts-gg",
"synExt": {
"engineCustom": {
"prompt": "η¨ι¦ζΈ―η²€θ―θ―΄"
}
}
}Compared with TTS-L1: TTS-GG spells the formats mulaw (TTS-L1: ulaw) and ogg_opus (TTS-L1: opus) β pass each engine's strings exactly as documented. The TTS-GG guide has no speed parameter; describe pace in the prompt instead (e.g. "speak slightly faster").
TTS-GG models β
| Model | Gemini model | Notes (per Google) |
|---|---|---|
tts-gg-2.5-flash | gemini-2.5-flash-tts | Default. Low latency and controllable; cost-efficient everyday use |
tts-gg-2.5-pro | gemini-2.5-pro-tts | Highest control; for structured workflows such as podcasts, audiobooks, customer support |
tts-gg-3.1-flash-preview | gemini-3.1-flash-tts-preview | Preview, low latency; on Google's side every voice on this model is Preview |
The "Gemini model" column is a mapping inferred from the naming; the notes quote Google's Gemini-TTS documentation. Which models are actually available to you depends on your account and region β treat the live response as the source of truth.
Available voices β
The integration guide points to Google's official list: Gemini-TTS Β· Voice options. As of this update there are 30; put the name straight into VoiceId:
| Gender | Voice names |
|---|---|
| Female (14) | Achernar Aoede Autonoe Callirrhoe Despina Erinome Gacrux Kore Laomedeia Leda Pulcherrima Sulafat Vindemiatrix Zephyr |
| Male (16) | Achird Algenib Algieba Alnilam Charon Enceladus Fenrir Iapetus Orus Puck Rasalgethi Sadachbia Sadaltager Schedar Umbriel Zubenelgenubi |
Gemini voices are not tied to a language: the same Kore can read Chinese, English, or Thai; accent and language come from TextLang, the text itself, and the prompt. Every voice has an audio sample on Google's page β listen before choosing.
Response β
| Parameter | Type | Notes |
|---|---|---|
| ErrorCode | Integer | 0 on success |
| Msg | String | Result message |
| AudioData | String | Base64 audio (returned when Output.OutputType=URL is not set) |
| AudioUrl | String | Audio URL, valid for 24 hours |
| ExtInfo | String | Extended info as a JSON string, including duration (seconds) |
Writing the style prompt β
engineCustom.prompt is the most valuable TTS-GG parameter. Google splits speech control into three levers β results are most stable when all three agree:
| Lever | Role | Where it lives on MPS |
|---|---|---|
| Style Prompt | Sets the emotional tone and delivery of the whole segment | synExt.engineCustom.prompt |
| Text Content | The semantics of the words; emotionally rich text is far more reliable than neutral text | Text |
| Markup Tags (Preview) | Inject a localized action or style change, e.g. [sigh], [short pause] | Inside Text β³ |
Guidance (per Google):
- Be specific. "Speak like a 1940s radio news announcer" beats "speak in an old-fashioned way"; "react with an amused laugh" beats a bare
[laughing]. - Match the text to the emotion. For a scared tone,
I think someone is in the house.works far better thanThe meeting is at 4 PM. - Put accents and dialects in the prompt. E.g.
Speak in Hong Kong Cantonese,with a light Singaporean English accent. - Test new prompts on one sentence before running a batch.
Common markup tags (Google, all Preview):
| Kind | Tags | Effect |
|---|---|---|
| Non-speech sounds | [sigh] [laughing] [uhm] | Inserts a sigh / laugh / hesitation; the tag itself is not spoken |
| Style modifiers | [sarcasm] [robotic] [shouting] [whispering] [extremely fast] | Changes tone, volume, or pace of the following speech |
| Pauses | [short pause] [medium pause] [long pause] | Silence of about 250ms / 500ms / 1000ms+ |
Test markup tags first
The TTS-GG integration guide only documents prompt; it does not say whether bracketed tags inside Text are passed through to Gemini unchanged. Synthesize one sentence to confirm before relying on tags β if they are treated as plain text, the bracketed word will be read aloud. Google also notes that adjective tags such as [scared], [curious], and [bored] are spoken; put emotions in the prompt instead.
Synchronous synthesis: TextToSpeech β
For single lines, short narration, and previews. Max 2000 characters per call β longer input fails, use the async API instead. Official reference: 1041/82311.
| Parameter | Type | Required | Example | Notes |
|---|---|---|---|---|
| Text | String | yes | Hello, and welcome. | Text to synthesize, β€ 2000 chars |
| VoiceId | String | yes | Kore | Gemini voice name, see Available voices |
| TextLang | String | no | en | Text language; auto-detected when omitted |
| Output.OutputType | String | no | URL | URL returns AudioUrl (valid 24 hours) instead of base64 |
| ExtParam | String | no | {"engine":"tts-gg", ...} | Engine and extended parameters (JSON string), see engine parameters |
Asynchronous synthesis: TextToSpeechAsync β
Long-form content (audiobook chapters, full narration scripts) goes async: submit, take the TaskId, poll for the result. Official reference: 1041/79693.
| Parameter | Type | Required | Example | Notes |
|---|---|---|---|---|
| Text | String | yes | Long text⦠| Text to synthesize; no 2000-char cap |
| VoiceId | String | yes | Charon | Gemini voice name |
| TextLang | String | no | en | Auto-detected when omitted |
| ExtParam | String | no | {"engine":"tts-gg","synExt":{...}} | Same as the sync API |
| Output | Object | no | {"OutputType":"URL"} | Output form |
Poll with DescribeTextToSpeechAsyncTask (official reference: 1041/79696):
| Parameter | Type | Notes |
|---|---|---|
| TaskId | String | Required |
| Status | String | success / fail / processing |
| AudioUrl | String | Synthesized audio URL |
| VoiceId | String | Voice used for this job |
| ExtInfo | String | Extension, e.g. {"duration":1.00325} |
ErrorCode returns 100 while the job is still processing β that is not a failure.
Code samples β
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))
# 1) Sync synthesis: tts-gg + 2.5 Pro + 48 kHz mp3 + a style prompt
req = models.TextToSpeechRequest()
req.from_json_string(json.dumps({
"Text": "Good evening, and welcome to tonight's show.",
"VoiceId": "Kore",
"Output": {"OutputType": "URL"},
"ExtParam": json.dumps({
"engine": "tts-gg",
"synExt": {
"model": "tts-gg-2.5-pro",
"format": "mp3",
"sampleRate": 48000,
"engineCustom": {"prompt": "A young, warm female TV host opening the show in a friendly way"}
}
})
}))
print(client.TextToSpeech(req).to_json_string())# 2) Long form: submit, then poll
req = models.TextToSpeechAsyncRequest()
req.from_json_string(json.dumps({
"Text": "<long text>",
"TextLang": "en",
"VoiceId": "Charon",
"ExtParam": json.dumps({
"engine": "tts-gg",
"synExt": {"engineCustom": {"prompt": "Calm, low, steady nature-documentary narration"}}
})
}))
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 / AudioUrlLimits and caveats β
- No voice cloning yet: to reproduce a real speaker, use
CloneVoiceon TTS-ElevenLabs. - Sync API caps at
2000characters per call; anything longer must useTextToSpeechAsync. - Google applies its own per-request limits: text and prompt β€
4000bytes each, β€8000bytes combined; output audio beyond about655 secondsis truncated. A Chinese character is about3bytes β watch Google's limit when pairing a long prompt with long text; how the MPS async API segments input is determined by the live response. AudioUrlexpires in24 hours. If you need the asset, copy it to your own COS β never treat the URL as the asset.20 requests/secondper API. Do your own concurrency control and retries (ErrorCode=100means processing, not failure).- Languages: Gemini-TTS has
24GA languages on Google's side (includingth-THThai,vi-VNVietnamese,id-IDIndonesian); Mandarincmn-CN, Cantonese, and others are Preview there. On MPS, keep passing MPS codes inTextLang(e.g.zh), and also state dialects such as Cantonese in theprompt. - A misspelled engine parameter fails silently. After changing parameters, synthesize one sentence and listen before running a batch.
Related docs β
On this site:
| Doc | Contents |
|---|---|
| MPS TTS Engines Compared | Capabilities, parameters and selection guidance across all seven external engines |
| TTS-ElevenLabs | The same APIs on the ElevenLabs engine (tts-l1), with cloning and character timestamps |
| TTS-MiniMax | The same APIs on MiniMax (minimax): cloning and voice design |
| TTS-Seed | The same APIs on TTS-Seed (tts-s): 24 emotion values |
| TTS-Fishaudio | The same APIs on Fish Audio (tts-f): inline emotion tags and zero-shot cloning |
| TTS-Index | The same APIs on IndexTTS (index-tts): a reference audio URL straight in VoiceId, 8-dimension emotion vector |
| TTS-Seedaudio | The same APIs on Seed Audio (tts-sa): the only engine that generates speech from an image, word-level timestamps |
| AI Dubbing | Full language swap on video, speaker replacement (ProcessMedia + dubbing template) |
| MPS API Reference | TC3 signing, common parameters, error codes |
| API Key environment variables | How to configure SecretId / SecretKey |
Official API references (Tencent Cloud international site Β· Media AI β Dubbing APIs): per-API links and purposes are in APIs and official references at the top. See Data Types, Common Params, Signature v3, and Error Codes.
Google official: Gemini-TTS (models, voices, prompts and markup tags, language list) Β· Voice options.