Skip to content

TTS-Seedaudio โ€‹

Updated

This page covers calling Seed Audio speech synthesis on MPS. Seed Audio is wired into MPS under the engine code tts-sa: the APIs, authentication, billing, task queries and storage all reuse the existing MPS speech-synthesis APIs. You switch to Seed Audio purely by setting "engine": "tts-sa" inside the ExtParam extension parameter, then add format, speed, reference resources and so on as needed.

Three things set tts-sa apart from every other TTS engine on MPS, and they are the main reasons to pick it:

  1. It can generate speech from an image โ€” put a reference image in references and the engine produces audio following the text in text_prompt. It is the only one of the seven engines that can do this, and the only one whose input side goes beyond "text + audio".
  2. One request can reference several audio clips, and the text picks which one โ€” up to 3 clips, referenced in text_prompt as @audio1, @audio2, with upload order strictly matching the numbering. On every other engine, reference audio means "one voice for the whole request".
  3. Word-level timestamps are a switch, not a model capability โ€” set audio_config.enable_subtitle to true and word-level timestamps come back in ExtInfo; it is off by default. Until now only ElevenLabs offered timestamps (character-level, via with_timestamps).

The async API is recommended

The TTS-SA integration guide says explicitly: the TTS-SA engine is slow, so the async API is recommended. Of the seven engines, only its guide and the IndexTTS one say so โ€” synchronous TextToSpeech works, but long text easily hits a timeout. For production, prefer TextToSpeechAsync plus polling.

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 one-line version: if you need speech generated from an image, several reference clips picked by name in the text, or word-level timestamps (and you do not need cloning) โ†’ this page.

APIs and official references โ€‹

All APIs below belong to the MPS "Media AI โ€“ Dubbing APIs" family, listed under Media AI โ€“ Dubbing APIs on the Tencent Cloud international site.

APIs that support tts-sa โ€‹

The TTS-SA integration guide lists these 4 APIs as switchable to Seed Audio through ExtParam.engine:

APIPurposeCall styleOfficial reference
TextToSpeechShort-text synthesis, returns audio directlysync1041/82311
TextToSpeechAsyncLong-text synthesis, returns a TaskId (recommended)async1041/79693
DescribeTextToSpeechAsyncTaskQuery an async result (Status / AudioUrl)sync1041/79696
DescribeVoicesList available system voicessync1041/79695

It brings the fourth API back

Neither the Fish Audio nor the IndexTTS guide lists DescribeVoices; the tts-sa one does โ€” so among the seven engines it has the same complete common subset as the first four: three synthesis APIs plus voice lookup. To query, just put {"engine": "tts-sa"} in ExtParam; there are no other required parameters.

Other APIs in the same family โ€‹

APIPurposeOn tts-saOfficial reference
CloneVoiceClone a voice from reference audio into a reusable VoiceIdโŒ the guide states "cloning not yet supported"1041/82312
DesignVoiceAsync / DescribeDesignTaskDesign a new voice from a text description / query itโณ 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 synthesise)โณ not listed in the guide1041/77775

โณ = not mentioned in the guide, so whether it can switch to Seed Audio is for a real call to decide; โŒ = the guide says it is unsupported.

"Cloning not yet supported" is not the same as "cannot use reference audio"

The guide opens with ps: cloning not yet supported, meaning there is no CloneVoice route for creating a voice โ€” you cannot obtain a reusable cloned VoiceId. But it can use reference audio: pass audio_url or audio_data in engineCustom.references and that request is synthesised in that clip's voice. The effect is close to zero-shot cloning; the difference is that every request must carry the audio again, and the result cannot be persisted as a reusable voice.

Switching engines: ExtParam.engine โ€‹

The MPS speech-synthesis APIs are engine-agnostic. What actually decides which engine synthesises is the engine field inside the ExtParam extension parameter.

ExtParam is a JSON string (not an object), with a fixed top-level shape:

json
{
  "engine": "tts-sa",
  "synExt": {
    "format": "mp3",
    "speed": 0.9,
    "engineCustom": {}
  }
}
  • engine โ€” required, always tts-sa.
  • synExt โ€” optional, the synthesis parameters MPS abstracts uniformly (format, sample rate, speed, volume, pitch).
  • synExt.engineCustom โ€” optional, passed through to Seed Audio's own parameters; reference resources and the subtitle switch both live here.

Outer level wins for duplicate keys, but references is the exception

synExt.xxx overrides synExt.engineCustom.xxx. To use a vendor-only parameter, put it only in engineCustom, not in both layers. The one exception is references: pass it and the reference resource determines the voice, so the outer VoiceId has no effect (the guide's wording: "when this parameter is passed, the upper-level VoiceId can be a mock value"). Fish Audio's references carries the same exemption โ€” across the seven engines, only these two parameters are explicitly exempted from the "outer level wins" rule.

Main tts-sa parameters โ€‹

synExt (the MPS abstraction layer) โ€‹

ParameterTypeRequiredNotes
modelStringNocurrently only tts-sa-v1
formatStringNowav (default) / mp3 / pcm / ogg_opus
sampleRateIntegerNo8000 / 16000 / 24000 / 32000 / 44100 / 48000, default 16000. ogg_opus supports only 48000
speedFloatNospeed, [0.5, 2], default 1.0
volFloatNovolume, [0.5, 2.0] โ€” 0.5 means half volume, 2.0 means double; no adjustment by default
pitchIntegerNopitch, [-12, 12]; higher means higher-pitched
engineCustomObjectNovendor-specific parameters, passed through to the engine

Its vol range differs from everyone else's

On MiniMax, TTS-Seed and Fish Audio, vol is (0, 10]. On tts-sa it is [0.5, 2.0], and the semantics differ too โ€” it is a multiplier (0.5 half, 2.0 double), not a 10-step scale. Reusing parameters across engines, vol: 5 applied to tts-sa is out of range and fails validation.

The hard constraint between ogg_opus and sample rate

With ogg_opus, the sample rate must be 48000, while the default sample rate is 16000 โ€” so writing only format: "ogg_opus" without changing sampleRate is a self-conflicting parameter set. Using opus means setting both. Also, its sample-rate options do not include 22050 (ElevenLabs, MiniMax and Fish Audio all do), but do include 48000 (only Gemini, TTS-Seed and this engine have it).

engineCustom.references (reference resources) โ€‹

references is an array (written as [{...}] in the guide's example) and decides which generation mode the request uses. The fields available on each array element:

ParameterTypeRequiredNotes
speakerStringNovoice ID
audio_dataStringNoreference audio, Base64-encoded
audio_urlStringNoreference audio URL; remote audio is supported
image_dataStringNoreference image, Base64-encoded
image_urlStringNoreference image URL

These five fields are mutually exclusive โ€” one per element

The guide's wording: "speaker, audio_data, audio_url, image_data and image_url are mutually exclusive; pass only one of them". To use several clips at once, put several elements in the array, each carrying one audio_url (or audio_data).

Quantity and size limits for reference resources:

TypeMax countPer-item limitSupported formats
Reference audioup to 3โ‰ค 30 seconds, โ‰ค 10 MBwav / mp3 / pcm / ogg_opus
Reference imageup to 1โ‰ค 10 MBjpeg / png / webp

engineCustom.audio_config (output configuration) โ€‹

ParameterTypeRequiredNotes
enable_subtitleBoolNoEnables the subtitle service, default false. Once on, word-level timestamps are returned and read from the ExtInfo extension info

For subtitle alignment, this switch must be set explicitly

enable_subtitle defaults to false, so omit it and you get no timestamps โ€” with no hint anywhere in the output. It looks like "the subtitle feature isn't there", rather than an error. What you get is word-level (ElevenLabs' with_timestamps is character-level). For Chinese, word-level is usually more useful: character-level treats a Han character and a punctuation mark alike, while word-level maps directly to the smallest displayable unit.

Three generation modes โ€‹

What you put in references decides which generation path the engine takes. This is where tts-sa differs most from the other engines โ€” elsewhere "reference audio" has exactly one purpose, cloning that voice, whereas here it is a multimodal input.

Text only โ€‹

Omit references and the engine generates audio from the prompt in text_prompt.

Audio reference โ€‹

Pass an audio reference (audio_url / audio_data) and the engine generates audio from that clip plus the prompt in text_prompt. In this mode you can also pin the voice with speaker (a voice ID).

Image reference โ€‹

Pass an image reference (image_url / image_data) and the engine generates audio following the text in text_prompt.

Image reference is unique to this engine

Of the seven engines, only tts-sa accepts image input. The guide spells out the three combinations as: text only, text + image, text + audio. This path reaches beyond "read the text aloud" โ€” the image supplies cues about vocal style or scene, while the words to speak still come from the text. The guide gives no mapping between image content and vocal outcome, so for a first run, test with a few visually distinct images before putting it into a production chain.

text_prompt is not in the parameter tables

All three mode descriptions revolve around text_prompt, yet the guide's parameter tables never define that field โ€” it is not under synExt, nor under references or audio_config. From context it should sit under engineCustom, as a sibling of references (a vendor pass-through parameter). Confirm its actual position with one minimal request before relying on this page's inference at scale. Also, the MPS API's own Text field is the body to synthesise. The guide never explains how text_prompt relates to Text, and that is the single largest uncertainty on this page.

The @audioN reference order โ€‹

With several reference clips, upload order must strictly match the @audioN numbering in text_prompt: the first clip is @audio1, the second @audio2, and so on.

Get the order wrong and nothing errors โ€” you just get the wrong voice

This is a positional convention, not a named reference โ€” the engine matches numbers by array index. If your code assembles references from a map or set (unstable ordering), @audio1 may point at a different clip. It shows up as "the voices got swapped", not as a parameter error, which makes it expensive to diagnose. Keep references as an ordered array in your wrapper, and generate the text_prompt numbering from that same ordered data.

Where VoiceId comes from โ€‹

tts-sa has two voice sources, depending on whether you pass references:

CaseWhat to put in VoiceIdActual voice source
No referencesa system voice name (from DescribeVoices)system voices
references passedany mock value will dothe reference resource (audio / image / speaker)

"Can be a mock value" is the guide's own wording โ€” but do not put junk there

The original says: "when this parameter is passed, the upper-level VoiceId can be a mock value; the actual voice follows this parameter". In other words, with references present the outer VoiceId has no effect, so its content does not change the result. In practice, still use a real system voice name rather than a placeholder like "x": if references silently fails to apply (say the audio could not be fetched), a request with a valid VoiceId still returns audio, whereas a placeholder fails validation outright.

Request examples โ€‹

Minimal request (text only, system voice) โ€‹

json
{
  "Text": "ๆ‚จๅฅฝ",
  "VoiceId": "zh_female_vv_uranus_bigtts",
  "ExtParam": "{\"engine\":\"tts-sa\",\"synExt\":{\"format\":\"mp3\",\"speed\":0.9}}"
}

The guide's example has a leading space in the engine value

Its synthesis example reads \"engine\":\" tts-sa\" โ€” one space before tts-sa. engine is matched exactly, so the space fails validation; this page uses the correct value "tts-sa". The same example's VoiceId is zh_female_vv_uranus_bigtts, which is in fact a TTS-Seed (tts-s) voice name. For tts-sa, take the system voices from what DescribeVoices actually returns rather than copying this value.

With reference audio (audio reference mode) โ€‹

json
{
  "engine": "tts-sa",
  "synExt": {
    "format": "mp3",
    "speed": 0.9,
    "engineCustom": {
      "references": [
        { "audio_url": "https://example.com/ref.wav" }
      ]
    }
  }
}

With references passed, the outer VoiceId has no effect โ€” the voice follows ref.wav.

Several reference clips (with @audioN) โ€‹

json
{
  "engine": "tts-sa",
  "synExt": {
    "format": "mp3",
    "engineCustom": {
      "references": [
        { "audio_url": "https://example.com/speaker_a.wav" },
        { "audio_url": "https://example.com/speaker_b.wav" }
      ]
    }
  }
}

The first array element is @audio1 (speaker_a.wav), the second is @audio2 (speaker_b.wav).

Image reference mode โ€‹

json
{
  "engine": "tts-sa",
  "synExt": {
    "format": "mp3",
    "engineCustom": {
      "references": [
        { "image_url": "https://example.com/scene.jpg" }
      ]
    }
  }
}

Turning on word-level timestamps โ€‹

json
{
  "engine": "tts-sa",
  "synExt": {
    "format": "mp3",
    "sampleRate": 24000,
    "engineCustom": {
      "audio_config": {
        "enable_subtitle": true
      }
    }
  }
}

Read the timestamps from the returned ExtInfo.

Listing system voices โ€‹

DescribeVoices only needs the engine in ExtParam:

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

Async synthesis โ€‹

For long text, or when image / multi-clip references are in play, async is the safer route:

  1. TextToSpeechAsync โ€” same parameters as the sync API, returns a TaskId.
  2. DescribeTextToSpeechAsyncTask โ€” poll with the TaskId, then read AudioUrl once Status is successful.

Limits and gotchas โ€‹

  • engine matches tts-sa exactly โ€” no surrounding whitespace (the guide's example has a typo, see above).
  • ExtParam is a string โ€” it must be an escaped JSON string; passing an object fails validation.
  • Cloning is not yet supported: there is no CloneVoice route, so no reusable cloned VoiceId. For a persistent, reusable voice, use ElevenLabs, MiniMax or Fish Audio.
  • references disables the outer VoiceId โ€” the explicit exception to the "outer level wins" rule.
  • Reference audio: โ‰ค 30 seconds and โ‰ค 10 MB each, up to 3 clips; reference image โ‰ค 10 MB, up to 1. The guide does not say what happens past those limits.
  • ogg_opus requires sampleRate: 48000 โ€” changing only the format is a conflicting parameter set.
  • vol is a multiplier, [0.5, 2.0] โ€” not the (0, 10] scale other engines use.
  • Word-level timestamps are off by default โ€” without enable_subtitle you get no timestamps and no warning.
  • @audioN matches by upload order โ€” scramble the order and you silently get the wrong voice.
  • The async API is recommended: the guide explicitly warns that it is slow.
  • No dedicated emotion or style parameter: of the seven engines, only this one and ElevenLabs have no emotion-style field. On tts-sa, style cues come from the reference resources and text_prompt, not from an enum.
  • text_prompt is undefined in the parameter tables, and its relationship with the MPS Text field is unexplained โ€” verify with a real call before going live.
DocNotes
MPS TTS Engines ComparedCapabilities, parameters and selection guidance across all seven external engines
AI DubbingOverview of MPS dubbing capabilities and the built-in engine
TTS-ElevenLabsSame APIs with the ElevenLabs engine (tts-l1), supports per-character timestamps
TTS-GeminiSame APIs with the Google Gemini-TTS engine (tts-gg), style via prompt
TTS-MiniMaxSame APIs with the MiniMax engine (minimax), supports cloning and voice design
TTS-SeedSame APIs with the TTS-Seed engine (tts-s), 24 emotion values
TTS-FishaudioSame APIs with the Fish Audio engine (tts-f), inline emotion tags and zero-shot cloning
TTS-IndexSame APIs with the IndexTTS engine (index-tts), a reference audio URL straight in VoiceId
MPS API ReferenceTC3 signing, common parameters, error codes
Media AI โ€“ Dubbing APIsOfficial API reference index

Built with VitePress ยท Deployed on Tencent EdgeOne Pages