Skip to content

TTS-Index โ€‹

Updated

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:

  1. VoiceId takes 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.
  2. Voice and emotion can come from two different audio files โ€” VoiceId decides who is speaking, engineCustom.emo_audio_url decides 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".
  3. 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:

APIWhat it doesCall styleOfficial reference
TextToSpeechShort text to speech, returns audio directlySync1041/82311
TextToSpeechAsyncLong text to speech, returns a TaskId (recommended)Async1041/79693
DescribeTextToSpeechAsyncTaskQuery async synthesis result (Status / AudioUrl)Sync1041/79696

Other APIs in the same catalog โ€‹

APIWhat it doesWorks with index-ttsOfficial reference
DescribeVoicesList available voicesโณ Not listed in the guide1041/79695
CloneVoiceClone a voice from reference audio into a reusable VoiceIdโณ Not listed in the guide1041/82312
DesignVoiceAsync / DescribeDesignTaskDesign a new voice from a text description / query the resultโณ Not listed in the guide1041/79694 / 1041/79598
UpdateVoice / DeleteVoiceModify / delete a cloned or designed voiceโณ Not listed in the guide1041/81214 / 1041/81215
ChangeVoiceVoice conversionโณ Not listed in the guide1041/83750
SyncDubbingEarly combined API (clone or synthesize)โณ Not listed in the guide1041/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; endpoint mps.intl.tencentcloudapi.com on the international site (mps.tencentcloudapi.com in the Chinese mainland).
  • Authentication is TC3-HMAC-SHA256 (SecretId / SecretKey); see Quick Start for the signing method.
  • Rate limit is 20 requests/second per 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:

LevelPurposeNotes
enginePick the engineAlways index-tts on this page
synExt.*Synthesis parameters normalized by MPSThe guide lists only model
synExt.engineCustom.*Passed through to IndexTTS as-isEmotion 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 โ€‹

ParameterTypeRequiredDescription
engineStringYesSet to index-tts
synExtObjectNoSynthesis extension parameters
synExt.modelStringNoModel to use: index-tts-2 (default) or index-tts-1.5
synExt.engineCustomObjectNoEngine-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 โ€‹

ValueNotesSupports engineCustom
index-tts-2Default model, 2.0 generationโœ…
index-tts-1.5Previous 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 โ€‹

ParameterTypeRequiredDescription
emo_audio_urlStringNoEmotion reference audio URL โ€” the emotion is taken from this clip, independently of the voice taken from VoiceId
emo_alphaFloatNoWeight of the emotion reference audio
emo_vectorArray of FloatNo8-dimension emotion vector, ordered [happy, angry, sad, afraid, disgusted, melancholic, surprised, calm], e.g. [0, 0, 0.8, 0, 0, 0, 0, 0]
use_randomBoolNoEnable random emotion sampling; defaults to false
use_emo_textBoolNoDerive the emotion vector automatically from text
emo_textStringNoAn 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):

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

PathParameterPrecisionGood for
8-dimension vectoremo_vectorHighest; each dimension is continuously adjustableBatch production needing reproducible, tunable output
Emotion reference audioemo_audio_url + emo_alphaHigh, but depends on the sampleYou already have a clip in the target emotion and want "read it like this"
Emotion description textemo_text (with use_emo_text)Medium; plain-language descriptionQuick experiments without tuning numbers
Random samplinguse_randomLow, not reproducibleVariety โ€” 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:

EngineWhat goes in VoiceId
index-ttsA reference audio URL, e.g. https://example.com/narration_voice_zh.wav
tts-s / tts-ggA system voice name (from DescribeVoices)
tts-l1 / minimax / tts-fA 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:

ParameterTypeDescription
durationFloatAudio 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 โ€‹

json
{
  "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 โ€‹

json
{
  "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 โ€‹

json
{
  "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 โ€‹

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

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 โ€‹

  • VoiceId takes 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.5 explicitly makes everything under engineCustom ineffective.
  • emo_text is not the text to synthesize: it only infers emotion, while the spoken content lives in Text โ€” confusing the two gets the emotion description read aloud.
  • ExtParam is 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_alpha has no declared range: the guide gives neither bounds nor a default, so probe a small range first.
  • No format / sampleRate / speed / vol / duration listed: model is 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 DescribeVoices and CloneVoice) is not necessarily unavailable.
PageNotes
MPS TTS Engines ComparedCapabilities, parameters and selection guidance across all seven external engines
AI DubbingOverview of MPS dubbing and its built-in engines
TTS-ElevenLabsThe ElevenLabs engine (tts-l1) on the same APIs, with character-level timestamps
TTS-GeminiThe Google Gemini-TTS engine (tts-gg) on the same APIs, style via prompt
TTS-MiniMaxThe MiniMax engine (minimax) on the same APIs, with cloning and voice design
TTS-SeedThe TTS-Seed engine (tts-s) on the same APIs, with 24 emotion presets
TTS-FishaudioThe Fish Audio engine (tts-f) on the same APIs, inline emotion tags and zero-shot cloning
TTS-SeedaudioThe same APIs on Seed Audio (tts-sa): the only engine that generates speech from an image, word-level timestamps
Quick StartAuthentication and request signing
Media AI โ€“ Dubbing APIsOfficial API catalog

Built with VitePress ยท Deployed on Tencent EdgeOne Pages