TTS-Index โ
This page covers calling IndexTTS speech synthesis through MPS. IndexTTS is wired into MPS under the engine code index-tts: APIs, authentication, billing, task queries and storage all reuse the existing MPS text-to-speech APIs. You only put "engine": "index-tts" in the ExtParam extension parameter to switch to IndexTTS, then add model and emotion parameters as needed.
Three things set index-tts apart from every other TTS engine on MPS, and they are the main reasons to pick it:
VoiceIdtakes a reference audio URL directly โ not a voice name, not a post-cloning ID. In other words, zero-shot cloning is its default mode of operation: there is no "create a voice first" step and no extra parameter to enable it.- Voice and emotion can come from two different audio files โ
VoiceIddecides who is speaking,engineCustom.emo_audio_urldecides with what emotion. The two are independent, and this is the only engine of the seven that supports "A's voice with B's emotion". - Five paths for emotion control โ reference audio, weight, an 8-dimension vector, random sampling, and a text description. Pick one based on how much precision you need; it is the finest-grained emotion control of the seven engines.
Prefer the async API
The IndexTTS Engine Integration Guide states explicitly: IndexTTS takes a while, so the async API is recommended. It and the tts-sa guide are the only two of the seven that say this โ the synchronous TextToSpeech does work, but long text tends to time out. Use TextToSpeechAsync plus polling in production.
Choosing between the seven engines
A full side-by-side comparison of all seven engines (API coverage, emotion mechanism, audio parameters, cloning) is on the Blog: MPS TTS Engines Compared. The short version: you want cloning from a single audio file with no voice to create first, or voice and emotion sampled separately โ this page.
APIs and official references โ
All APIs below belong to the MPS "Media AI โ Dubbing APIs" catalog; the official references live under Media AI โ Dubbing APIs on the Tencent Cloud international site.
APIs that support index-tts โ
The IndexTTS Engine Integration Guide lists these 3 APIs as switchable to IndexTTS via ExtParam.engine:
| API | What it does | Call style | Official reference |
|---|---|---|---|
TextToSpeech | Short text to speech, returns audio directly | Sync | 1041/82311 |
TextToSpeechAsync | Long text to speech, returns a TaskId (recommended) | Async | 1041/79693 |
DescribeTextToSpeechAsyncTask | Query async synthesis result (Status / AudioUrl) | Sync | 1041/79696 |
Other APIs in the same catalog โ
| API | What it does | Works with index-tts | Official reference |
|---|---|---|---|
DescribeVoices | List available voices | โณ Not listed in the guide | 1041/79695 |
CloneVoice | Clone a voice from reference audio into a reusable VoiceId | โณ Not listed in the guide | 1041/82312 |
DesignVoiceAsync / DescribeDesignTask | Design a new voice from a text description / query the result | โณ Not listed in the guide | 1041/79694 / 1041/79598 |
UpdateVoice / DeleteVoice | Modify / delete a cloned or designed voice | โณ Not listed in the guide | 1041/81214 / 1041/81215 |
ChangeVoice | Voice conversion | โณ Not listed in the guide | 1041/83750 |
SyncDubbing | Early combined API (clone or synthesize) | โณ Not listed in the guide | 1041/77775 |
โณ = not mentioned in the integration guide; whether it can be switched to IndexTTS is best confirmed by an actual call.
Neither DescribeVoices nor CloneVoice is listed โ and that is self-consistent
The index-tts integration guide is the shortest of the seven, covering only 3 APIs โ one fewer than tts-f, which at least lists CloneVoice. Both gaps matter little here: VoiceId is the reference audio URL, so you neither enumerate system voices via DescribeVoices nor swap a reference for an ID via CloneVoice. To reuse a voice, keep that audio URL on your own side.
Shared conventions:
- API version
2019-06-12; endpointmps.intl.tencentcloudapi.comon the international site (mps.tencentcloudapi.comin the Chinese mainland). - Authentication is TC3-HMAC-SHA256 (SecretId / SecretKey); see Quick Start for the signing method.
- Rate limit is
20 requests/secondper API.
How it compares with the other engines โ
MPS currently offers seven external TTS engines. The full side-by-side comparison (API coverage, emotion mechanism, audio parameters, cloning, selection guidance) is on the Blog: MPS TTS Engines Compared โ the comparison table is maintained only there, so the engine pages cannot drift apart.
Where index-tts sits: the only engine that takes reference audio directly in VoiceId, and the only one that can sample voice and emotion separately. The trade-off is that its guide lists no normalized audio parameters at all โ no format, sample rate, speed or volume.
Switching engines: ExtParam.engine โ
The MPS text-to-speech APIs are engine-agnostic. Which engine runs the synthesis is decided by ExtParam, a JSON string field. index-tts uses three levels:
| Level | Purpose | Notes |
|---|---|---|
engine | Pick the engine | Always index-tts on this page |
synExt.* | Synthesis parameters normalized by MPS | The guide lists only model |
synExt.engineCustom.* | Passed through to IndexTTS as-is | Emotion audio, emotion vector, emotion text (2.0+ models only) |
ExtParam is a string in the request, not an object โ the JSON must be escaped and passed as a string (see Request samples).
The guide lists no format / sampleRate / speed / vol / duration
The other five guides all provide a set of normalized synExt audio parameters. The index-tts guide provides only model. That means audio format, sample rate, speed, volume and target duration are all unverifiable from the guide โ test before relying on them. Do not copy the parameter table from tts-f or tts-s: that is another engine's declared surface and is no evidence about this one.
index-tts parameters โ
| Parameter | Type | Required | Description |
|---|---|---|---|
engine | String | Yes | Set to index-tts |
synExt | Object | No | Synthesis extension parameters |
synExt.model | String | No | Model to use: index-tts-2 (default) or index-tts-1.5 |
synExt.engineCustom | Object | No | Engine-specific parameters passed through to IndexTTS. 2.0+ models only |
Confirm the model parameter name by calling it
In the guide's parameter table, the "specify the model" row is also named synExt โ the same name as the object on the row above it, yet typed String. One field cannot be both an Object and a String, so based on context and the naming convention of the other five engines this page records it as synExt.model. If the call fails validation, retry with the literal synExt from the original.
Models โ
| Value | Notes | Supports engineCustom |
|---|---|---|
index-tts-2 | Default model, 2.0 generation | โ |
index-tts-1.5 | Previous generation | โ Below 2.0 |
Emotion capability is tied to the model version
Every emotion parameter under engineCustom is 2.0+ only. Setting model explicitly to index-tts-1.5 while also passing emotion parameters means the emotion part is silently ignored โ leaving model unset, so the default index-tts-2 applies, is actually the safer choice.
engineCustom parameters โ
| Parameter | Type | Required | Description |
|---|---|---|---|
emo_audio_url | String | No | Emotion reference audio URL โ the emotion is taken from this clip, independently of the voice taken from VoiceId |
emo_alpha | Float | No | Weight of the emotion reference audio |
emo_vector | Array of Float | No | 8-dimension emotion vector, ordered [happy, angry, sad, afraid, disgusted, melancholic, surprised, calm], e.g. [0, 0, 0.8, 0, 0, 0, 0, 0] |
use_random | Bool | No | Enable random emotion sampling; defaults to false |
use_emo_text | Bool | No | Derive the emotion vector automatically from text |
emo_text | String | No | An emotion description in plain text, converted automatically into an emotion vector. Note this is not the text to synthesize |
No value range given for emo_alpha
The guide describes emo_alpha only as "weight of the emotion reference audio" and gives neither a range nor a default. "Weight" usually implies [0, 1], but that is an inference โ test a few values to find the boundaries before running a batch, and do not assume anything above 1.0 is valid.
Parameter sample โ
A complete ExtParam object (expanded for readability; it must be escaped into a string in a real request):
{
"engine": "index-tts",
"synExt": {
"engineCustom": {
"emo_text": "You scared me to death! Are you a ghost?"
}
}
}emo_text here is an emotion description, not the text to synthesize โ what gets spoken goes in the request's Text field.
The guide's sample contains a JSON comment; copying it verbatim fails to parse
The guide's sample appends an inline // emotion description, not the text to synthesize comment after emo_text. Standard JSON does not allow comments, so a verbatim copy is rejected as a parameter error. This page drops the comment and states the same point in prose.
Five paths for emotion control โ
Emotion in index-tts is not an enum value but five mutually substitutable kinds of input. Ordered from most to least controllable:
| Path | Parameter | Precision | Good for |
|---|---|---|---|
| 8-dimension vector | emo_vector | Highest; each dimension is continuously adjustable | Batch production needing reproducible, tunable output |
| Emotion reference audio | emo_audio_url + emo_alpha | High, but depends on the sample | You already have a clip in the target emotion and want "read it like this" |
| Emotion description text | emo_text (with use_emo_text) | Medium; plain-language description | Quick experiments without tuning numbers |
| Random sampling | use_random | Low, not reproducible | Variety โ e.g. several takes of the same line |
| None | โ | โ | Follow whatever emotion the VoiceId reference audio already carries |
How to fill the 8-dimension vector
The eight dimensions are, in order, [happy, angry, sad, afraid, disgusted, melancholic, surprised, calm]. The guide's sample [0, 0, 0.8, 0, 0, 0, 0, 0] puts 0.8 on the third dimension (sad) and leaves the rest at 0 โ a single targeted emotion. Blended emotions should in principle allow several dimensions at once, but the guide does not say whether normalization is required (whether the dimensions must sum to 1). That is undeclared behavior โ test before blending.
The relationship between use_emo_text and emo_text is unspecified
use_emo_text ("derive the emotion vector automatically from text") and emo_text ("provide a specific textual emotion description") are two separate parameters, but the guide never says whether use_emo_text must be set to true when only emo_text is passed. The guide's own sample passes emo_text alone, which is what this page records. If the emotion has no effect, add "use_emo_text": true and retry.
What happens if several paths are passed at once
The guide gives no precedence between the emotion paths. The safe approach is one at a time โ emo_vector for precise and reproducible results, emo_audio_url to imitate a sample. Do not pass both.
Voice (VoiceId) โ
This is the biggest difference between index-tts and the other five engines:
| Engine | What goes in VoiceId |
|---|---|
index-tts | A reference audio URL, e.g. https://example.com/narration_voice_zh.wav |
tts-s / tts-gg | A system voice name (from DescribeVoices) |
tts-l1 / minimax / tts-f | A system voice name, or a voice ID returned by CloneVoice |
In other words, index-tts has no concept of a voice list โ each request carries a reference audio clip and is synthesized in that voice.
What this design saves, and what it costs
It saves: creating, storing and managing the lifecycle of voices is entirely unnecessary, and both DescribeVoices and CloneVoice drop out of the flow. That suits UGC scenarios (one voice per user, discarded after use) and batch jobs where voices far outnumber reuses. It costs: when the same voice is used thousands of times, every request makes the server fetch and process that reference clip again โ an extra round trip, plus the obligation to keep that URL reachable long-term. Host reference audio on your own CDN or COS; do not use links that expire.
Format and duration requirements for reference audio are undeclared
The guide only says "put the reference audio URL in VoiceId" and shows a .wav sample. It gives no format allowlist, duration guidance or size limit. The tts-f guide does suggest "10โ30 seconds of clear speech with minimal background noise" for reference audio, which is a useful rule of thumb โ but that is Fish Audio's statement, not IndexTTS's, so do not treat it as authoritative here. Confirm the real requirements by calling the API.
Output extension info: ExtInfo โ
The ExtInfo field on a synthesis result is a JSON string with a single field today:
| Parameter | Type | Description |
|---|---|---|
duration | Float | Audio duration in seconds |
For example {"duration":1.00325}. Use it when aligning subtitles by duration or concatenating audio tracks.
No character-level timestamps
index-tts reports only the overall duration; it provides no per-character or per-sentence timestamps. For karaoke-style word-by-word alignment, use with_timestamps on TTS-ElevenLabs.
Request samples โ
Synthesis via TextToSpeech โ
{
"Text": "Hello",
"VoiceId": "https://example.cos-internal.ap-nanjing.tencentcos.cn/common/reel/test/narration_voice_zh.wav",
"ExtParam": "{\"engine\":\"index-tts\"}"
}VoiceId holds a reference audio URL, not a voice name; the value of ExtParam is an escaped JSON string, not a nested object.
This is the minimal working request
With no model (so the default index-tts-2 applies) and no emotion parameters, the output follows the voice and emotion of the reference audio itself. Verify the pipeline in this shape first, then add emotion parameters one at a time.
With an emotion description โ
{
"Text": "When did you come in?",
"VoiceId": "https://example.com/narration_voice_zh.wav",
"ExtParam": "{\"engine\":\"index-tts\",\"synExt\":{\"engineCustom\":{\"emo_text\":\"You scared me to death! Are you a ghost?\"}}}"
}Note that Text and emo_text are two different pieces of content: Text is what gets spoken, while emo_text is used only to infer the emotion.
Precise emotion via the 8-dimension vector โ
{
"Text": "He never came back.",
"VoiceId": "https://example.com/narration_voice_zh.wav",
"ExtParam": "{\"engine\":\"index-tts\",\"synExt\":{\"engineCustom\":{\"emo_vector\":[0,0,0.8,0,0,0,0,0]}}}"
}The third dimension is "sad", set to 0.8, with the rest left at 0.
Sampling voice and emotion separately โ
{
"Text": "Congratulations, you passed.",
"VoiceId": "https://example.com/speaker_a.wav",
"ExtParam": "{\"engine\":\"index-tts\",\"synExt\":{\"engineCustom\":{\"emo_audio_url\":\"https://example.com/happy_sample.wav\",\"emo_alpha\":0.8}}}"
}The voice comes from speaker_a.wav and the emotion from happy_sample.wav โ this combination is unique to index-tts.
Async synthesis and query (recommended) โ
Submit long text with TextToSpeechAsync โ ExtParam is written exactly as in the sync API โ and it returns a TaskId. Then poll Status with DescribeTextToSpeechAsyncTask and fetch the audio from AudioUrl once it completes.
Because IndexTTS takes a while, production pipelines should default to async, keeping the sync API for short test calls.
Limits and gotchas โ
VoiceIdtakes a reference audio URL, not a voice name โ the biggest difference from the other five engines, and something your abstraction layer must handle explicitly.- The reference audio URL must stay reachable: it is fetched on every request, so avoid expiring presigned links.
- Prefer the async API: the guide warns that IndexTTS takes a while, and long text over the sync API tends to time out.
- Emotion parameters are 2.0+ only: setting
index-tts-1.5explicitly makes everything underengineCustomineffective. emo_textis not the text to synthesize: it only infers emotion, while the spoken content lives inTextโ confusing the two gets the emotion description read aloud.ExtParamis a string: it must be an escaped JSON string in the request; passing an object fails validation.- Strip the JSON comment from the sample: the guide's sample carries a
//comment, which standard JSON rejects, so a verbatim copy fails to parse. emo_alphahas no declared range: the guide gives neither bounds nor a default, so probe a small range first.- No
format/sampleRate/speed/vol/durationlisted:modelis the only normalized parameter in the guide; confirm anything else by calling the API. - Normalization of the 8-dimension vector is undeclared: test before blending dimensions, as it is unclear whether they must sum to 1.
- Items marked โณ should be confirmed by calling: the โ
/ โณ marks on this page reflect what the IndexTTS Engine Integration Guide happens to list; an API it omits (including
DescribeVoicesandCloneVoice) is not necessarily unavailable.
Related pages โ
| Page | Notes |
|---|---|
| MPS TTS Engines Compared | Capabilities, parameters and selection guidance across all seven external engines |
| AI Dubbing | Overview of MPS dubbing and its built-in engines |
| TTS-ElevenLabs | The ElevenLabs engine (tts-l1) on the same APIs, with character-level timestamps |
| TTS-Gemini | The Google Gemini-TTS engine (tts-gg) on the same APIs, style via prompt |
| TTS-MiniMax | The MiniMax engine (minimax) on the same APIs, with cloning and voice design |
| TTS-Seed | The TTS-Seed engine (tts-s) on the same APIs, with 24 emotion presets |
| TTS-Fishaudio | The Fish Audio engine (tts-f) on the same APIs, inline emotion tags and zero-shot cloning |
| TTS-Seedaudio | The same APIs on Seed Audio (tts-sa): the only engine that generates speech from an image, word-level timestamps |
| Quick Start | Authentication and request signing |
| Media AI โ Dubbing APIs | Official API catalog |