Skip to content

TTS-Gemini ​

Updated

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 ​

APIWhat it doesModeVia GeminiOfficial reference
TextToSpeechShort text to speech (≀ 2000 chars), returns audio directlysyncβœ… engine: tts-gg1041/82311
TextToSpeechAsyncLong text to speech, returns TaskIdasyncβœ… engine: tts-gg1041/79693
DescribeTextToSpeechAsyncTaskFetch the async synthesis result (Status / AudioUrl)syncfollows the task1041/79696

Other APIs in the same directory ​

APIWhat it doesVia GeminiOfficial reference
CloneVoiceClone a voice from reference audio❌ the guide states cloning is not supported yet1041/82312
DesignVoiceAsync / DescribeDesignTaskDesign a voice from a text description / fetch the result⏳ not covered by the guide1041/79694 / 1041/79598
DescribeVoicesFilter available voices⏳ not covered by the guide; Gemini voices use their official names, see Available voices1041/79695
UpdateVoice / DeleteVoiceEdit / delete cloned or designed voices⏳ no cloned voices, rarely needed1041/81214 / 1041/81215
ChangeVoiceVoice conversion⏳ not covered by the guide1041/83750
SyncDubbingEarlier all-in-one API (clone or synthesize)⏳ not covered by the guide1041/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; endpoint mps.intl.tencentcloudapi.com on the international site (mps.tencentcloudapi.com on the China site).
  • Authentication is TC3-HMAC-SHA256 (SecretId / SecretKey); see Quick Start for signing.
  • Rate limit is 20 requests/second per API.

Choosing an engine ​

NeedUse
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 outputThis page
A specific speaker's voice (cloning)TTS-ElevenLabs / TTS-MiniMax / TTS-Fishaudio (Gemini has no cloning)
Per-character timestamps for karaoke subtitlesTTS-ElevenLabs (the guide does not document timestamps for TTS-GG)
Enumerated emotions or scenario broadcast stylesTTS-MiniMax / TTS-Seed
You have a video and need a full language swap or speaker replacementAI 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.

text
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:

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

The matching minimum request (from the integration guide):

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

Two more things to keep in mind:

  • VoiceId is the Gemini voice name (e.g. Kore) β€” not an MPS system voice s1_… or a cloned v1_…. Reusing another engine's VoiceId will most likely fail with "voice not found".
  • Misspelled keys do not error. Keys the engine does not recognize inside ExtParam are 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.

ParameterTypeRequiredNotes
engineStringyestts-gg
synExtObjectnoSpeech-synthesis extension parameters
synExt.modelStringnoModel, default tts-gg-2.5-flash. See model list
synExt.formatStringnoAudio format: wav (default) / mp3 / pcm / ogg_opus / alaw / mulaw
synExt.sampleRateIntegernoSample rate: 8000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000, default 16000
synExt.engineCustomObjectnoEngine-specific parameters
synExt.engineCustom.promptStringnoCustom 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):

json
{
  "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 ​

ModelGemini modelNotes (per Google)
tts-gg-2.5-flashgemini-2.5-flash-ttsDefault. Low latency and controllable; cost-efficient everyday use
tts-gg-2.5-progemini-2.5-pro-ttsHighest control; for structured workflows such as podcasts, audiobooks, customer support
tts-gg-3.1-flash-previewgemini-3.1-flash-tts-previewPreview, 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:

GenderVoice 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 ​

ParameterTypeNotes
ErrorCodeInteger0 on success
MsgStringResult message
AudioDataStringBase64 audio (returned when Output.OutputType=URL is not set)
AudioUrlStringAudio URL, valid for 24 hours
ExtInfoStringExtended 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:

LeverRoleWhere it lives on MPS
Style PromptSets the emotional tone and delivery of the whole segmentsynExt.engineCustom.prompt
Text ContentThe semantics of the words; emotionally rich text is far more reliable than neutral textText
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 than The 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):

KindTagsEffect
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.

ParameterTypeRequiredExampleNotes
TextStringyesHello, and welcome.Text to synthesize, ≀ 2000 chars
VoiceIdStringyesKoreGemini voice name, see Available voices
TextLangStringnoenText language; auto-detected when omitted
Output.OutputTypeStringnoURLURL returns AudioUrl (valid 24 hours) instead of base64
ExtParamStringno{"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.

ParameterTypeRequiredExampleNotes
TextStringyesLong text…Text to synthesize; no 2000-char cap
VoiceIdStringyesCharonGemini voice name
TextLangStringnoenAuto-detected when omitted
ExtParamStringno{"engine":"tts-gg","synExt":{...}}Same as the sync API
OutputObjectno{"OutputType":"URL"}Output form

Poll with DescribeTextToSpeechAsyncTask (official reference: 1041/79696):

ParameterTypeNotes
TaskIdStringRequired
StatusStringsuccess / fail / processing
AudioUrlStringSynthesized audio URL
VoiceIdStringVoice used for this job
ExtInfoStringExtension, e.g. {"duration":1.00325}

ErrorCode returns 100 while the job is still processing β€” that is not a failure.

Code samples ​

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))

# 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())
python
# 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 / AudioUrl

Limits and caveats ​

  • No voice cloning yet: to reproduce a real speaker, use CloneVoice on TTS-ElevenLabs.
  • Sync API caps at 2000 characters per call; anything longer must use TextToSpeechAsync.
  • Google applies its own per-request limits: text and prompt ≀ 4000 bytes each, ≀ 8000 bytes combined; output audio beyond about 655 seconds is truncated. A Chinese character is about 3 bytes β€” 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.
  • AudioUrl expires in 24 hours. If you need the asset, copy it to your own COS β€” never treat the URL as the asset.
  • 20 requests/second per API. Do your own concurrency control and retries (ErrorCode=100 means processing, not failure).
  • Languages: Gemini-TTS has 24 GA languages on Google's side (including th-TH Thai, vi-VN Vietnamese, id-ID Indonesian); Mandarin cmn-CN, Cantonese, and others are Preview there. On MPS, keep passing MPS codes in TextLang (e.g. zh), and also state dialects such as Cantonese in the prompt.
  • A misspelled engine parameter fails silently. After changing parameters, synthesize one sentence and listen before running a batch.

On this site:

DocContents
MPS TTS Engines ComparedCapabilities, parameters and selection guidance across all seven external engines
TTS-ElevenLabsThe same APIs on the ElevenLabs engine (tts-l1), with cloning and character timestamps
TTS-MiniMaxThe same APIs on MiniMax (minimax): cloning and voice design
TTS-SeedThe same APIs on TTS-Seed (tts-s): 24 emotion values
TTS-FishaudioThe same APIs on Fish Audio (tts-f): inline emotion tags and zero-shot cloning
TTS-IndexThe same APIs on IndexTTS (index-tts): a reference audio URL straight in VoiceId, 8-dimension emotion vector
TTS-SeedaudioThe same APIs on Seed Audio (tts-sa): the only engine that generates speech from an image, word-level timestamps
AI DubbingFull language swap on video, speaker replacement (ProcessMedia + dubbing template)
MPS API ReferenceTC3 signing, common parameters, error codes
API Key environment variablesHow 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.

Built with VitePress Β· Deployed on Tencent EdgeOne Pages