TTS-Seedaudio โ
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:
- It can generate speech from an image โ put a reference image in
referencesand the engine produces audio following the text intext_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". - One request can reference several audio clips, and the text picks which one โ up to 3 clips, referenced in
text_promptas@audio1,@audio2, with upload order strictly matching the numbering. On every other engine, reference audio means "one voice for the whole request". - Word-level timestamps are a switch, not a model capability โ set
audio_config.enable_subtitletotrueand word-level timestamps come back inExtInfo; it is off by default. Until now only ElevenLabs offered timestamps (character-level, viawith_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:
| API | Purpose | Call style | Official reference |
|---|---|---|---|
TextToSpeech | Short-text synthesis, returns audio directly | sync | 1041/82311 |
TextToSpeechAsync | Long-text synthesis, returns a TaskId (recommended) | async | 1041/79693 |
DescribeTextToSpeechAsyncTask | Query an async result (Status / AudioUrl) | sync | 1041/79696 |
DescribeVoices | List available system voices | sync | 1041/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 โ
| API | Purpose | On tts-sa | Official reference |
|---|---|---|---|
CloneVoice | Clone a voice from reference audio into a reusable VoiceId | โ the guide states "cloning not yet supported" | 1041/82312 |
DesignVoiceAsync / DescribeDesignTask | Design a new voice from a text description / query it | โณ 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 synthesise) | โณ not listed in the guide | 1041/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:
{
"engine": "tts-sa",
"synExt": {
"format": "mp3",
"speed": 0.9,
"engineCustom": {}
}
}engineโ required, alwaystts-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) โ
| Parameter | Type | Required | Notes |
|---|---|---|---|
model | String | No | currently only tts-sa-v1 |
format | String | No | wav (default) / mp3 / pcm / ogg_opus |
sampleRate | Integer | No | 8000 / 16000 / 24000 / 32000 / 44100 / 48000, default 16000. ogg_opus supports only 48000 |
speed | Float | No | speed, [0.5, 2], default 1.0 |
vol | Float | No | volume, [0.5, 2.0] โ 0.5 means half volume, 2.0 means double; no adjustment by default |
pitch | Integer | No | pitch, [-12, 12]; higher means higher-pitched |
engineCustom | Object | No | vendor-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:
| Parameter | Type | Required | Notes |
|---|---|---|---|
speaker | String | No | voice ID |
audio_data | String | No | reference audio, Base64-encoded |
audio_url | String | No | reference audio URL; remote audio is supported |
image_data | String | No | reference image, Base64-encoded |
image_url | String | No | reference 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:
| Type | Max count | Per-item limit | Supported formats |
|---|---|---|---|
| Reference audio | up to 3 | โค 30 seconds, โค 10 MB | wav / mp3 / pcm / ogg_opus |
| Reference image | up to 1 | โค 10 MB | jpeg / png / webp |
engineCustom.audio_config (output configuration) โ
| Parameter | Type | Required | Notes |
|---|---|---|---|
enable_subtitle | Bool | No | Enables 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:
| Case | What to put in VoiceId | Actual voice source |
|---|---|---|
No references | a system voice name (from DescribeVoices) | system voices |
references passed | any mock value will do | the 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) โ
{
"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) โ
{
"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) โ
{
"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 โ
{
"engine": "tts-sa",
"synExt": {
"format": "mp3",
"engineCustom": {
"references": [
{ "image_url": "https://example.com/scene.jpg" }
]
}
}
}Turning on word-level timestamps โ
{
"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:
{
"engine": "tts-sa"
}Async synthesis โ
For long text, or when image / multi-clip references are in play, async is the safer route:
TextToSpeechAsyncโ same parameters as the sync API, returns aTaskId.DescribeTextToSpeechAsyncTaskโ poll with theTaskId, then readAudioUrlonceStatusis successful.
Limits and gotchas โ
enginematchestts-saexactly โ no surrounding whitespace (the guide's example has a typo, see above).ExtParamis a string โ it must be an escaped JSON string; passing an object fails validation.- Cloning is not yet supported: there is no
CloneVoiceroute, so no reusable clonedVoiceId. For a persistent, reusable voice, use ElevenLabs, MiniMax or Fish Audio. referencesdisables the outerVoiceIdโ 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_opusrequiressampleRate: 48000โ changing only the format is a conflicting parameter set.volis a multiplier,[0.5, 2.0]โ not the(0, 10]scale other engines use.- Word-level timestamps are off by default โ without
enable_subtitleyou get no timestamps and no warning. @audioNmatches 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. Ontts-sa, style cues come from the reference resources andtext_prompt, not from an enum. text_promptis undefined in the parameter tables, and its relationship with the MPSTextfield is unexplained โ verify with a real call before going live.
Related docs โ
| Doc | Notes |
|---|---|
| MPS TTS Engines Compared | Capabilities, parameters and selection guidance across all seven external engines |
| AI Dubbing | Overview of MPS dubbing capabilities and the built-in engine |
| TTS-ElevenLabs | Same APIs with the ElevenLabs engine (tts-l1), supports per-character timestamps |
| TTS-Gemini | Same APIs with the Google Gemini-TTS engine (tts-gg), style via prompt |
| TTS-MiniMax | Same APIs with the MiniMax engine (minimax), supports cloning and voice design |
| TTS-Seed | Same APIs with the TTS-Seed engine (tts-s), 24 emotion values |
| TTS-Fishaudio | Same APIs with the Fish Audio engine (tts-f), inline emotion tags and zero-shot cloning |
| TTS-Index | Same APIs with the IndexTTS engine (index-tts), a reference audio URL straight in VoiceId |
| MPS API Reference | TC3 signing, common parameters, error codes |
| Media AI โ Dubbing APIs | Official API reference index |