Skip to content

TTS-ElevenLabs ​

Updated

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 ​

APIWhat it doesModeVia ElevenLabsOfficial reference
TextToSpeechShort text to speech (≀ 2000 chars), returns audio directlysyncβœ… engine: tts-l11041/82311
TextToSpeechAsyncLong text to speech, returns TaskId; can translate before synthesisasyncβœ… engine: tts-l11041/79693
DescribeTextToSpeechAsyncTaskFetch the async synthesis result (Status / AudioUrl)syncfollows the task1041/79696
CloneVoiceClone a voice from one reference clip, returns a reusable VoiceIdsyncβœ… engine: tts-l11041/82312
DesignVoiceAsyncDesign a new voice from a text description, returns TaskIdasyncβœ… engine: tts-l11041/79694
DescribeDesignTaskFetch the voice design result (VoiceId / preview audio)syncfollows the task1041/79598
DescribeVoicesFilter available voices by type, gender, age, language, tagsyncβœ… pass engine to list ElevenLabs voices1041/79695

Other APIs in the same directory ​

APIWhat it doesModeVia ElevenLabsOfficial reference
UpdateVoiceEdit a cloned/designed voice's name, description, gender, age, languages, tags, scenes, preview audiosync⏳ not covered by the guide1041/81214
DeleteVoiceDelete a cloned/designed voice (frees one of the 100 slots)sync⏳ not covered by the guide1041/81215
ChangeVoiceVoice conversion: re-render input audio in the given VoiceIdsync⏳ not covered by the guide1041/83750
SyncDubbingEarlier all-in-one API: clone or synthesize in a single callsync⏳ not covered by the guide1041/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; 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.

Where this page sits relative to AI Dubbing ​

TaskWhich 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 replacementAI Dubbing
You need a script re-recorded in the original speaker's voiceVoice 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.

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

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-l1" }

Parameter layers and precedence:

LayerLocationNotes
Engine selectionExtParam.enginetts-l1 routes to ElevenLabs; omit it for the MPS default engine
MPS-wide parametersExtParam.synExt.*Cross-engine fields such as format, sampleRate, duration
Engine-specific parametersExtParam.synExt.model, speedDefined by TTS-L1, see the next section
Native passthroughExtParam.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 VoiceId cloned or designed with tts-l1 must also be synthesized with engine: "tts-l1"; DescribeVoices without engine returns the full pool, and those IDs may be rejected by TTS-L1.
  • 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-L1 engine parameters ​

From the TTS-L1 engine integration guide. These apply only when engine is tts-l1, to both TextToSpeech and TextToSpeechAsync.

ParameterTypeRequiredNotes
engineStringyestts-l1
synExt.modelStringnoModel, default tts-l1-multilingual_v2. See model list
synExt.formatStringnoOutput format: mp3 / wav / opus / alaw / ulaw, default wav
synExt.speedFloatnoSpeaking rate, 1.0 is natural; supports [0.7, 1.2]
synExt.engineCustomObjectnoContainer for native ElevenLabs parameters
synExt.engineCustom.with_timestampsBoolnoReturn 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:

json
{
  "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_settings tunes expressiveness vs. voice fidelity. Lower stability gives wider emotional swing; higher keeps it even. use_speaker_boost pushes similarity to the original voice.
  • previous_text / next_text supply 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 ​

ModelNotes
tts-l1-multilingual_v2Default. Best multilingual coverage with balanced emotion; the safe general choice
tts-l1-v3v3 series; more expressive, good for narration and character work
tts-l1-v4v4 series, newer; availability depends on your account entitlement
tts-l1-v4_turboLow-latency v4, for real-time or high-concurrency use
tts-l1-turbo_v2_5Low latency; strong cost/quality trade-off for batch long-form
tts-l1-flash_v2_5Lowest 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 ​

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, see below

Parsed ExtInfo:

FieldTypeNotes
durationFloatAudio duration in seconds
engineExtObjectEngine-specific extension
engineExt.alignmentObjectPer-character timestamps for the source text
engineExt.normalized_alignmentObjectPer-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.

ParameterTypeRequiredExampleNotes
TextStringyesHello, and welcome.Text to synthesize, ≀ 2000 chars
VoiceIdStringyes5mZxJZhSmJTjL7GoYfYISystem voice (s1_…) or a v1_… returned by clone/design
TextLangStringnozhText language; auto-detected when omitted. See language list
Output.OutputTypeStringnoURLURL returns AudioUrl (valid 24 hours) instead of base64
ExtParamStringno{"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.

ParameterTypeRequiredExampleNotes
TextStringyesLong text…Text to synthesize; no 2000-char cap
VoiceIdStringyesv1_…Voice ID
TextLangStringnozhAuto-detected when omitted
ExtParamStringno{"engine":"tts-l1","synExt":{...}}Same as the sync API; also accepts transExt to translate before synthesis
OutputObjectno{"OutputType":"URL"}Output form

transExt translates before synthesis β€” one less call when producing multiple language versions:

json
{
  "transExt": {
    "transInfo": { "transDst": "en" },
    "transRequirement": "Do not translate anything inside quotes"
  }
}

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.

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.

ParameterTypeRequiredExampleNotes
AudioDataStringone of twobase64Reference audio as base64
AudioUrlStringone of twohttps://…/voice.wavReference audio URL, used when AudioData is empty
AudioLangStringnozhReference audio language, default Chinese
VoiceProfile.NameStringnobrand-narrator-01Voice name, useful for DescribeVoices lookups
VoiceProfile.Gender / Age / Labels / ScenesString / Arraynomale / middle_aged / ["raspy"]Voice attributes for query and matching
TextStringnoHello, this is a preview.Preview text; returns a short preview clip
TextLangStringnoenPreview text language
Output.OutputTypeStringnoURLOutput form for the preview clip
ExtParamStringno{"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.

ParameterTypeRequiredExampleNotes
PromptStringyesMale movie-trailer narrator, deep and resonantVoice description; more specific is more stable
VoiceProfileObjectno{"Name":"commentary-male"}Voice attributes
TextStringnoOn a stormy night…Preview text, ≀ 500 chars; preview audio is returned only if set
ExtParamStringno{"promptEnhance":true}promptEnhance expands the description; engine can be set too

Returns TaskId; poll with DescribeDesignTask (official reference: 1041/79598):

ParameterTypeNotes
TaskIdStringRequired
StatusStringsuccess / fail / processing
VoiceIdStringGenerated voice ID (may be null)
AudioUrlStringPreview URL (only when Text was supplied)
ExtInfoStringExtension, 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.

ParameterTypeRequiredNotes
VoiceTypeStringnosystem / clone / design / all (default)
VoiceIdStringnoExact match by ID
VoiceNameStringnoFuzzy match by name
Gender / AgeStringnomale/female/unknown; child/teenager/youth/middle_aged/senior/unknown
Languages.NArray of Stringnoe.g. ["zh"]
Labels.N / Scenes.NArray of Stringnoe.g. ["professional"] / ["narration"]
PageNum / PageSizeIntegernoPagination; omit to return everything
ExtParamStringnoSet {"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 ​

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

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

  • alignment maps to the text you sent, character by character;
  • normalized_alignment maps 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):

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

NeedApproach
Just a sentence-level timeline, splitting on punctuation yourselfSkip with_timestamps; use ExtInfo.duration plus an estimated rate
Karaoke-style per-character highlightingEnable 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 trackSend previous_text / next_text per segment; offset each timeline by accumulated duration

Limits and caveats ​

  • Sync API caps at 2000 characters per call; anything longer must use TextToSpeechAsync.
  • AudioUrl expires in 24 hours. If you need the asset, copy it to your own COS β€” never treat the URL as the asset.
  • Cloned plus designed voices: 100 by default per account.
  • 20 requests/second per API. Do your own concurrency control and retries (ErrorCode=100 means processing, not failure).
  • TextLang is 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 ExtParam are 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.

On this site:

DocContents
MPS TTS Engines ComparedCapabilities, parameters and selection guidance across all seven external engines
TTS-GeminiThe same APIs on Google Gemini-TTS (tts-gg): prompt-driven style, no cloning
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. 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.

Built with VitePress Β· Deployed on Tencent EdgeOne Pages