TTS-ElevenLabs β
This page documents how to call the ElevenLabs model family on MPS. ElevenLabs is exposed as engine code tts-l1: the APIs, authentication, billing, task polling, and storage are all the standard MPS speech APIs β you switch to ElevenLabs only by writing "engine": "tts-l1" inside the extended parameter ExtParam, then add engine-specific parameters as needed.
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.
Synthesis and voices β
| API | What it does | Mode | Via ElevenLabs | Official reference |
|---|---|---|---|---|
TextToSpeech | Short text to speech (β€ 2000 chars), returns audio directly | sync | β
engine: tts-l1 | 1041/82311 |
TextToSpeechAsync | Long text to speech, returns TaskId; can translate before synthesis | async | β
engine: tts-l1 | 1041/79693 |
DescribeTextToSpeechAsyncTask | Fetch the async synthesis result (Status / AudioUrl) | sync | follows the task | 1041/79696 |
CloneVoice | Clone a voice from one reference clip, returns a reusable VoiceId | sync | β
engine: tts-l1 | 1041/82312 |
DesignVoiceAsync | Design a new voice from a text description, returns TaskId | async | β
engine: tts-l1 | 1041/79694 |
DescribeDesignTask | Fetch the voice design result (VoiceId / preview audio) | sync | follows the task | 1041/79598 |
DescribeVoices | Filter available voices by type, gender, age, language, tag | sync | β
pass engine to list ElevenLabs voices | 1041/79695 |
Other APIs in the same directory β
| API | What it does | Mode | Via ElevenLabs | Official reference |
|---|---|---|---|---|
UpdateVoice | Edit a cloned/designed voice's name, description, gender, age, languages, tags, scenes, preview audio | sync | β³ not covered by the guide | 1041/81214 |
DeleteVoice | Delete a cloned/designed voice (frees one of the 100 slots) | sync | β³ not covered by the guide | 1041/81215 |
ChangeVoice | Voice conversion: re-render input audio in the given VoiceId | sync | β³ not covered by the guide | 1041/83750 |
SyncDubbing | Earlier all-in-one API: clone or synthesize in a single call | sync | β³ not covered by the guide | 1041/77775 |
β
= the TTS-L1 engine integration guide explicitly supports engine: "tts-l1"; β³ = these APIs also take ExtParam, but the guide does not mention TTS-L1 for them β whether they can route to ElevenLabs 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.
Where this page sits relative to AI Dubbing β
| Task | Which page |
|---|---|
| You have text and need audio (voice-over, audiobook, podcast) | This page (TTS) |
| You have a video/audio file and need a full language swap or speaker replacement | AI Dubbing |
| You need a script re-recorded in the original speaker's voice | Voice cloning below + TTS |
Engine switching: calling an external engine through ExtParam β
The MPS speech 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 / CloneVoice / DesignVoiceAsync / DescribeVoices
β
ββ ExtParam without engine ββββββΊ MPS default engine
β
ββ ExtParam.engine = "tts-l1" βββΊ ElevenLabs
β
ββ synExt.* parameters MPS has abstracted (model / format / speed / sampleRate β¦)
ββ synExt.engineCustom.* native ElevenLabs parameters, forwarded verbatimExtParam is a JSON string (not an object), so it must be escaped a second time inside the request body. Minimum form:
{ "engine": "tts-l1" }Parameter layers and precedence:
| Layer | Location | Notes |
|---|---|---|
| Engine selection | ExtParam.engine | tts-l1 routes to ElevenLabs; omit it for the MPS default engine |
| MPS-wide parameters | ExtParam.synExt.* | Cross-engine fields such as format, sampleRate, duration |
| Engine-specific parameters | ExtParam.synExt.model, speed | Defined by TTS-L1, see the next section |
| Native passthrough | ExtParam.synExt.engineCustom.* | Forwarded to ElevenLabs verbatim, field names identical |
On a name collision the outer parameter wins. If both synExt.speed and synExt.engineCustom.speed are present, synExt.speed is used. So prefer expressing a parameter in synExt; reserve engineCustom for ElevenLabs-only parameters that MPS has not abstracted.
Two more things to keep in mind:
- Voice IDs are bound to their engine. A
VoiceIdcloned or designed withtts-l1must also be synthesized withengine: "tts-l1";DescribeVoiceswithoutenginereturns the full pool, and those IDs may be rejected by TTS-L1. - Misspelled keys do not error. Keys the engine does not recognize inside
ExtParamare usually ignored silently, and you get audible-but-wrong audio.
TTS-L1 engine parameters β
From the TTS-L1 engine integration guide. These apply only when engine is tts-l1, to both TextToSpeech and TextToSpeechAsync.
| Parameter | Type | Required | Notes |
|---|---|---|---|
| engine | String | yes | tts-l1 |
| synExt.model | String | no | Model, default tts-l1-multilingual_v2. See model list |
| synExt.format | String | no | Output format: mp3 / wav / opus / alaw / ulaw, default wav |
| synExt.speed | Float | no | Speaking rate, 1.0 is natural; supports [0.7, 1.2] |
| synExt.engineCustom | Object | no | Container for native ElevenLabs parameters |
| synExt.engineCustom.with_timestamps | Bool | no | Return character-level timestamps (see alignment) |
synExt also carries the MPS-wide fields listed in the official reference: sampleRate (8000 / 16000 / 22050 / 24000 / 32000 / 44100, default 16000) and duration (target length in seconds). Note the MPS default engine only supports wav / mp3 for format; opus / alaw / ulaw are TTS-L1 only.
engineCustom accepts any ElevenLabs synthesis parameter; field definitions are in the ElevenLabs Text to Speech API reference. Three common groups:
{
"voice_settings": {
"stability": 0.5,
"similarity_boost": 0.75,
"style": 0.0,
"use_speaker_boost": true
},
"previous_text": "Last line of the previous segment",
"next_text": "First line of the next segment"
}voice_settingstunes expressiveness vs. voice fidelity. Lowerstabilitygives wider emotional swing; higher keeps it even.use_speaker_boostpushes similarity to the original voice.previous_text/next_textsupply context so consecutive calls keep one continuous tone β essential when you synthesize a long script segment by segment, otherwise every segment sounds like a fresh start.
TTS-L1 models β
| Model | Notes |
|---|---|
tts-l1-multilingual_v2 | Default. Best multilingual coverage with balanced emotion; the safe general choice |
tts-l1-v3 | v3 series; more expressive, good for narration and character work |
tts-l1-v4 | v4 series, newer; availability depends on your account entitlement |
tts-l1-v4_turbo | Low-latency v4, for real-time or high-concurrency use |
tts-l1-turbo_v2_5 | Low latency; strong cost/quality trade-off for batch long-form |
tts-l1-flash_v2_5 | Lowest latency; best when quality can be relaxed |
Naming is tts-l1- plus the ElevenLabs model suffix (multilingual_v2 β eleven_multilingual_v2, turbo_v2_5 β eleven_turbo_v2_5). Which models are actually available to you depends on your account and region β treat the live response as the source of truth. Per-model capabilities are described in ElevenLabs Models.
Response and ExtInfo β
| 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, see below |
Parsed ExtInfo:
| Field | Type | Notes |
|---|---|---|
| duration | Float | Audio duration in seconds |
| engineExt | Object | Engine-specific extension |
| engineExt.alignment | Object | Per-character timestamps for the source text |
| engineExt.normalized_alignment | Object | Per-character timestamps for the normalized text |
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 | 5mZxJZhSmJTjL7GoYfYI | System voice (s1_β¦) or a v1_β¦ returned by clone/design |
| TextLang | String | no | zh | Text language; auto-detected when omitted. See language list |
| Output.OutputType | String | no | URL | URL returns AudioUrl (valid 24 hours) instead of base64 |
| ExtParam | String | no | {"engine":"tts-l1", ...} | 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 | v1_β¦ | Voice ID |
| TextLang | String | no | zh | Auto-detected when omitted |
| ExtParam | String | no | {"engine":"tts-l1","synExt":{...}} | Same as the sync API; also accepts transExt to translate before synthesis |
| Output | Object | no | {"OutputType":"URL"} | Output form |
transExt translates before synthesis β one less call when producing multiple language versions:
{
"transExt": {
"transInfo": { "transDst": "en" },
"transRequirement": "Do not translate anything inside quotes"
}
}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.
Voice cloning: CloneVoice β
Give it one reference clip (at least 5 seconds, single speaker, no background music) and get back a reusable VoiceId. Official reference: 1041/82312.
| Parameter | Type | Required | Example | Notes |
|---|---|---|---|---|
| AudioData | String | one of two | base64 | Reference audio as base64 |
| AudioUrl | String | one of two | https://β¦/voice.wav | Reference audio URL, used when AudioData is empty |
| AudioLang | String | no | zh | Reference audio language, default Chinese |
| VoiceProfile.Name | String | no | brand-narrator-01 | Voice name, useful for DescribeVoices lookups |
| VoiceProfile.Gender / Age / Labels / Scenes | String / Array | no | male / middle_aged / ["raspy"] | Voice attributes for query and matching |
| Text | String | no | Hello, this is a preview. | Preview text; returns a short preview clip |
| TextLang | String | no | en | Preview text language |
| Output.OutputType | String | no | URL | Output form for the preview clip |
| ExtParam | String | no | {"engine":"tts-l1"} | Engine selection |
The response carries VoiceId (v1_ plus a long encrypted base64 string, often 80+ characters). Store it whole and pass it back unchanged β it contains /, +, and =; truncate or URL-encode it and you get a misleading "voice not found" error.
Cloned plus designed voices are capped at 100 per account by default; beyond that, clean up with DeleteVoice or request a quota increase. If a voice's attributes are wrong, fix them with UpdateVoice instead of re-cloning.
Voice design: DesignVoiceAsync β
No reference audio β describe the voice in words and let the model create one. Useful early on, when you have no matching voice actor yet. Official reference: 1041/79694.
| Parameter | Type | Required | Example | Notes |
|---|---|---|---|---|
| Prompt | String | yes | Male movie-trailer narrator, deep and resonant | Voice description; more specific is more stable |
| VoiceProfile | Object | no | {"Name":"commentary-male"} | Voice attributes |
| Text | String | no | On a stormy night⦠| Preview text, †500 chars; preview audio is returned only if set |
| ExtParam | String | no | {"promptEnhance":true} | promptEnhance expands the description; engine can be set too |
Returns TaskId; poll with DescribeDesignTask (official reference: 1041/79598):
| Parameter | Type | Notes |
|---|---|---|
| TaskId | String | Required |
| Status | String | success / fail / processing |
| VoiceId | String | Generated voice ID (may be null) |
| AudioUrl | String | Preview URL (only when Text was supplied) |
| ExtInfo | String | Extension, e.g. {"name":"Sweet female"} |
The same prompt does not guarantee the same voice β if you need reproducibility, save the returned VoiceId instead of redesigning.
Listing voices: DescribeVoices β
Filter voices by type, gender, age, language, and tag. Official reference: 1041/79695.
| Parameter | Type | Required | Notes |
|---|---|---|---|
| VoiceType | String | no | system / clone / design / all (default) |
| VoiceId | String | no | Exact match by ID |
| VoiceName | String | no | Fuzzy match by name |
| Gender / Age | String | no | male/female/unknown; child/teenager/youth/middle_aged/senior/unknown |
| Languages.N | Array of String | no | e.g. ["zh"] |
| Labels.N / Scenes.N | Array of String | no | e.g. ["professional"] / ["narration"] |
| PageNum / PageSize | Integer | no | Pagination; omit to return everything |
| ExtParam | String | no | Set {"engine":"tts-l1"} when listing ElevenLabs voices |
Returns TotalCount and Voices[]; each entry has VoiceId / Name / Category / Gender / Age / Languages / Labels / Scenes / Description / AudioUrl (preview).
Without engine, you get the full MPS voice pool including non-ElevenLabs engines β a VoiceId from there may not be accepted by TTS-L1. Check this first when debugging "invalid voice".
ElevenLabs' own public voice library is at elevenlabs.io/app/default-voices; pick a style there, then verify the ID through DescribeVoices.
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-l1 + v3 model + 0.9x rate + character timestamps
req = models.TextToSpeechRequest()
req.from_json_string(json.dumps({
"Text": "Hello, this is TTS-L1 speaking.",
"TextLang": "en",
"VoiceId": "5mZxJZhSmJTjL7GoYfYI",
"Output": {"OutputType": "URL"},
"ExtParam": json.dumps({
"engine": "tts-l1",
"synExt": {
"model": "tts-l1-v3",
"format": "mp3",
"speed": 0.9,
"engineCustom": {
"voice_settings": {"stability": 0.5, "use_speaker_boost": True},
"with_timestamps": True
}
}
})
}))
print(client.TextToSpeech(req).to_json_string())# 2) Voice cloning: one reference clip in, one VoiceId out (sync)
req = models.CloneVoiceRequest()
req.from_json_string(json.dumps({
"AudioUrl": "https://example.com/reference-voice.wav",
"AudioLang": "en",
"VoiceProfile": {"Name": "brand-narrator-01", "Gender": "male"},
"Text": "Hello, this is a preview.",
"ExtParam": json.dumps({"engine": "tts-l1"})
}))
resp = client.CloneVoice(req)
print(resp.VoiceId) # v1_... store whole, reuse in TTS# 3) Long form: submit, then poll
req = models.TextToSpeechAsyncRequest()
req.from_json_string(json.dumps({
"Text": "<long text>",
"TextLang": "en",
"VoiceId": "<VoiceId>",
"ExtParam": json.dumps({"engine": "tts-l1", "synExt": {"model": "tts-l1-turbo_v2_5"}})
}))
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 / AudioUrlCharacter timestamps and subtitle alignment β
with_timestamps: true adds engineExt.alignment and engineExt.normalized_alignment to the response β the input for word-level subtitles and for hitting picture cuts with voice-over.
alignmentmaps to the text you sent, character by character;normalized_alignmentmaps to the normalized text actually spoken (numbers, abbreviations, and symbols get expanded), so it is not a 1:1 match with your source.
The underlying layout is ElevenLabs' native three equal-length arrays (characters / character_start_times_seconds / character_end_times_seconds):
{
"engineExt": {
"alignment": {
"characters": ["H", "i"],
"character_start_times_seconds": [0.0, 0.18],
"character_end_times_seconds": [0.18, 0.42]
}
}
}Log one full response before writing the parser
That layout is ElevenLabs' native shape; the TTS-L1 integration guide only states "timestamp info per character" without expanding the field names. Log one complete response and confirm the keys before building word-level subtitles β do not hard-code the sample above, field names can shift between engine versions.
Practical guidance:
| Need | Approach |
|---|---|
| Just a sentence-level timeline, splitting on punctuation yourself | Skip with_timestamps; use ExtInfo.duration plus an estimated rate |
| Karaoke-style per-character highlighting | Enable with_timestamps; use normalized_alignment for audio sync and alignment for the original text |
| Voice-over matching picture (lip-sync, hit points) | Validate total length with duration; adjust synExt.speed (0.7~1.2) or trim text if it overruns |
| Stitching segments into one track | Send previous_text / next_text per segment; offset each timeline by accumulated duration |
Limits and caveats β
- Sync API caps at
2000characters per call; anything longer must useTextToSpeechAsync. AudioUrlexpires in24 hours. If you need the asset, copy it to your own COS β never treat the URL as the asset.- Cloned plus designed voices:
100by default per account. 20 requests/secondper API. Do your own concurrency control and retries (ErrorCode=100means processing, not failure).TextLangis auto-detected when omitted. For mixed-language copy, set the primary language explicitly β a bad guess changes how the entire passage is read.- A misspelled engine parameter fails silently: unknown keys inside
ExtParamare usually ignored, and you get audible-but-wrong audio. After changing parameters, synthesize one sentence and listen before running a batch.
TextLang language codes β
Officially supported on the MPS side (40 codes). Note Hungarian is hun and Filipino is fil β not the ISO hu/tl. Pass the strings exactly as given:
zh Chinese / en English / ja Japanese / de German / fr French / ko Korean / ru Russian / uk Ukrainian / pt Portuguese / it Italian / es Spanish / id Indonesian / nl Dutch / tr Turkish / fil Filipino / ms Malay / el Greek / fi Finnish / hr Croatian / sk Slovak / pl Polish / sv Swedish / hi Hindi / bg Bulgarian / ro Romanian / ar Arabic / cs Czech / da Danish / ta Tamil / hun Hungarian / vi Vietnamese / no Norwegian / yue Cantonese / th Thai / he Hebrew / ca Catalan / nn Nynorsk / af Afrikaans / fa Persian / sl Slovenian
Which languages a given model covers depends on that model's support in ElevenLabs β multilingual_v2 has the widest coverage; the turbo / flash tiers are weaker on smaller languages.
Related docs β
On this site:
| Doc | Contents |
|---|---|
| MPS TTS Engines Compared | Capabilities, parameters and selection guidance across all seven external engines |
| TTS-Gemini | The same APIs on Google Gemini-TTS (tts-gg): prompt-driven style, no cloning |
| 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. Data structures (VoiceProfile, VoiceInfo, VoiceUpdateFields, SyncDubbingOutputOption) are in Data Types; see Common Params, Signature v3, and Error Codes.
ElevenLabs official: Text to Speech API (engineCustom field definitions) Β· Models Β· Default Voices.