TTS-Fishaudio โ
This page covers how to call Fish Audio speech synthesis on MPS. Fish Audio is plugged into MPS under the engine code tts-f: the APIs, authentication, billing, task queries and storage are all the existing MPS speech-synthesis APIs. You switch to Fish Audio simply by writing "engine": "tts-f" in the ExtParam extension field, then add model, speed, reference audio and other parameters as needed.
Three things set tts-f apart from every other TTS engine on MPS โ and they are the main reasons to pick it:
- Emotion lives in the text body, not in a separate parameter โ you prepend a tag such as
[excited]toText, and tag content can be customised. - Zero-shot cloning can be done inline โ pass a reference clip in
engineCustom.referencesand that request is synthesised in that voice, without callingCloneVoicefirst to obtain aVoiceId. - LLM-style sampling controls โ
temperature/top_p/repetition_penaltytune expressiveness and repetition, whilelatencypicks a point on the quality/latency curve.
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. Short version: need custom emotion tags or cloning without creating a voice first โ this page.
APIs and Official References โ
All of the APIs below belong to the MPS "Media AI โ Dubbing APIs" group; the official references live under Media AI โ Dubbing APIs on Tencent Cloud International.
APIs that support tts-f โ
The TTS-F Engine Integration Guide lists these 4 APIs as switchable to Fish Audio via ExtParam.engine:
| API | What it does | Mode | Official reference |
|---|---|---|---|
TextToSpeech | Short text to speech, returns audio directly | Sync | 1041/82311 |
CloneVoice | Clone a voice from reference audio, returns a reusable VoiceId | Sync | 1041/82312 |
TextToSpeechAsync | Long text to speech, returns a TaskId | Async | 1041/79693 |
DescribeTextToSpeechAsyncTask | Query async synthesis result (Status / AudioUrl) | Sync | 1041/79696 |
Other APIs in the same group โ
| API | What it does | Works with tts-f | Official reference |
|---|---|---|---|
DescribeVoices | List available voices | โณ Not listed in the guide | 1041/79695 |
DesignVoiceAsync / DescribeDesignTask | Design a new voice from a text description / query the result | โณ Not listed in the guide | 1041/79694 / 1041/79598 |
UpdateVoice / DeleteVoice | Update / 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 | Legacy combined API (clone or synthesise) | โณ Not listed in the guide | 1041/77775 |
โณ = not mentioned in the integration guide; confirm with an actual call whether it can be switched to Fish Audio.
DescribeVoices is outside the guide's scope
Of the seven engines, only the tts-f and index-tts integration guides omit DescribeVoices (tts-sa, added later, does list it). Fortunately tts-f barely depends on it: to pin a voice you can either use the VoiceId returned by CloneVoice, or pass reference audio inline via references below. If you really need to enumerate system voices, verify with a short request first.
Common conventions:
- API version
2019-06-12; endpointmps.intl.tencentcloudapi.comon the International site (mps.tencentcloudapi.comin mainland China). - Authentication is TC3-HMAC-SHA256 (SecretId / SecretKey) throughout; see Quick Start for the signing method.
- Rate limit is
20 requests/secondper API.
Switching engines: ExtParam.engine โ
The MPS speech-synthesis APIs are engine-agnostic; the ExtParam JSON-string field decides which engine runs the job. tts-f uses three layers:
| Layer | Purpose | Notes |
|---|---|---|
engine | Pick the engine | Always tts-f on this page |
synExt.* | Synthesis parameters normalised by MPS | Model, format, sample rate, duration, speed, volume |
synExt.engineCustom.* | Parameters passed through to Fish Audio | Reference audio, sampling controls, latency tier |
In the request ExtParam is a string, not an object โ the JSON must be escaped and passed as a string (see Examples).
The outer layer wins for duplicate parameters โ except references
When the same key appears in both synExt.xxx and synExt.engineCustom.xxx, the outer layer wins. The one exception is references: the guide states explicitly that "the outer layer takes precedence for identical parameters (except references)". In other words, once you pass references, that determines the actual voice โ even if the outer VoiceId says something else.
Main tts-f parameters โ
| Parameter | Type | Required | Description |
|---|---|---|---|
engine | String | Yes | Set to tts-f |
synExt | Object | No | Speech-synthesis extension parameters |
synExt.model | String | No | Model: tts-f-s2.1-pro (default), tts-f-s2-pro, tts-f-s1 |
synExt.format | String | No | Output audio format: wav, mp3, opus. Default wav |
synExt.sampleRate | Integer | No | Sample rate: 8000, 16000, 22050, 24000, 32000, 44100. Default 16000 |
synExt.duration | Float | No | Target audio duration |
synExt.speed | Float | No | Speaking rate, range [0.5, 2], default 1.0 |
synExt.vol | Float | No | Volume, range (0, 10], default 1.0 |
synExt.engineCustom | Object | No | Engine-specific parameters passed through to Fish Audio |
Model list โ
| Value | Notes |
|---|---|
tts-f-s2.1-pro | Default model, current-generation Pro |
tts-f-s2-pro | Previous-generation Pro |
tts-f-s1 | S1 model |
The default model has no published price
The price list in the integration guide only covers s2-pro and s1 (both $15.00 per million UTF-8 bytes); the default model s2.1-pro is not priced. Before running a batch on default parameters, confirm the billing basis for s2.1-pro with your account team, or specify one of the priced models explicitly.
engineCustom parameters โ
| Parameter | Type | Required | Description |
|---|---|---|---|
references | Array of Object | No | Array of reference audio samples; audio and its matching text must both be supplied. When present, the outer VoiceId can be a mock value โ this parameter determines the actual voice |
references[].audio_data | String | No | Reference audio as Base64 (request body must stay under 10 MB). Mutually exclusive with audio_url |
references[].audio_url | String | No | Reference audio URL, remote references supported. WAV, MP3 and FLAC accepted; for best results use 10โ30 seconds of clear speech with minimal background noise |
references[].text | String | No | The exact transcript of the sample audio. Accuracy is critical to clone quality |
temperature | Float | No | Controls expressiveness. Higher is more varied, lower is more stable. Range [0, 1], default 0.7 |
top_p | Float | No | Controls diversity via sampling. Range [0, 1], default 0.7 |
latency | String | No | Quality/latency trade-off: normal best quality / balanced reduced latency / low lowest latency. Default normal |
repetition_penalty | Integer | No | Penalty for repetitive audio patterns; above 1.0 reduces repetition. Default 1.2 |
The "mutually exclusive" note on audio_data is a typo in the guide
The guide describes references.audio_data as "mutually exclusive with audio_data" โ i.e. with itself. In context it should read "mutually exclusive with audio_url": both carry the same reference clip, one as Base64 and one as a URL. This page documents the latter reading.
Parameter example โ
A complete ExtParam object (expanded for readability; the actual request needs it escaped as a string):
{
"engine": "tts-f",
"synExt": {
"speed": 0.9,
"engineCustom": {
"references": [
{
"audio_url": "https://example.com/ref.mp3",
"text": "Hello"
}
],
"temperature": 0.7,
"latency": "normal"
}
}
}Two formatting issues in the guide's example, corrected here
In the guide's extension-parameter example: โ there is no comma between "audio_url": "xxx.mp3" and "text": "ไฝ ๅฅฝ", so copying it verbatim yields invalid JSON; โก references is declared as Array of Object in the parameter table, yet the example passes a single object. This page follows the declared type and writes an array. If testing shows only an object is accepted, revert to the guide's form.
Emotion control: inline tags in Text โ
tts-f has no separate emotion parameter. Instead you put the tag at the start of the Text body:
[happy] What a beautiful day!
[sad] I'm sorry to hear that.
[excited] This is amazing news!Common emotion tags โ
The guide lists 24 common tags, and tag content can be customised โ this is not a closed enum:
| Emotion | Tag | Tone | Typical context |
|---|---|---|---|
| Happy | [happy] | Cheerful, upbeat | Good news, greetings |
| Sad | [sad] | Melancholic, downcast | Sympathy, bad news |
| Angry | [angry] | Frustrated, aggressive | Complaints, warnings |
| Excited | [excited] | Energetic, enthusiastic | Announcements, celebrations |
| Calm | [calm] | Peaceful, relaxed | Instructions, meditation |
| Nervous | [nervous] | Anxious, uncertain | Disclaimers, apologies |
| Confident | [confident] | Assertive, self-assured | Presentations, sales |
| Surprised | [surprised] | Shocked, amazed | Reactions, discoveries |
| Satisfied | [satisfied] | Content, pleased | Confirmations, reviews |
| Delighted | [delighted] | Very pleased, joyful | Celebrations, compliments |
| Scared | [scared] | Frightened, fearful | Warnings, horror stories |
| Worried | [worried] | Concerned, troubled | Concerns, questions |
| Upset | [upset] | Disturbed, distressed | Complaints, problems |
| Frustrated | [frustrated] | Annoyed, exasperated | Technical issues, delays |
| Depressed | [depressed] | Very sad, hopeless | Serious topics |
| Empathetic | [empathetic] | Understanding, caring | Support, counselling |
| Embarrassed | [embarrassed] | Ashamed, awkward | Apologies, mistakes |
| Disgusted | [disgusted] | Repelled, revolted | Negative reviews |
| Moved | [moved] | Emotionally touched | Heartfelt moments |
| Proud | [proud] | Accomplished, satisfied | Achievements, praise |
| Relaxed | [relaxed] | At ease, casual | Casual conversation |
| Grateful | [grateful] | Thankful, appreciative | Thanks, appreciation |
| Curious | [curious] | Inquisitive, interested | Questions, exploration |
| Sarcastic | [sarcastic] | Ironic, mocking | Humour, criticism |
Both sides of inline tags
Upside: emotion can change sentence by sentence within one piece of text, with no need to split it into multiple requests; and because tags are free-form, you can try styles beyond the listed set. Cost: the tag is part of the body, so upstream copy assembly can easily end up reading the bracketed text aloud. Agree on a convention that emotion tags may only appear at the start of a sentence, and validate it before storage.
Voices (VoiceId) โ
tts-f gives you two routes to a voice; pick by scenario:
| Scenario | Approach | VoiceId |
|---|---|---|
| The voice is reused often (e.g. a fixed presenter) | Call CloneVoice once to create it | Use the returned VoiceId, e.g. 7f92f8afb8ec43bf81429cc1c9199cb1 |
| One-off, or very many distinct voices | Pass engineCustom.references directly | Can be a mock value โ references determines the actual voice |
When inline zero-shot cloning fits
The references route removes the whole "create voice โ store VoiceId โ manage voice lifecycle" workflow. It suits UGC scenarios (one voice per user, discarded after use) or batch jobs where the number of voices far exceeds reuse. Conversely, if one voice will be used thousands of times, creating it once with CloneVoice saves bandwidth โ otherwise every request re-uploads the reference audio.
Examples โ
Speech synthesis TextToSpeech โ
{
"Text": "[excited] Hello there",
"VoiceId": "7f92f8afb8ec43bf81429cc1c9199cb1",
"ExtParam": "{\"engine\":\"tts-f\",\"synExt\":{\"speed\":0.9}}"
}Note that ExtParam is an escaped JSON string, not a nested object; and the emotion tag [excited] goes in Text, not in ExtParam.
Zero-shot cloning: pin the voice inline with references โ
{
"Text": "[calm] Welcome to this episode",
"VoiceId": "placeholder",
"ExtParam": "{\"engine\":\"tts-f\",\"synExt\":{\"speed\":0.9,\"engineCustom\":{\"references\":[{\"audio_url\":\"https://example.com/ref.mp3\",\"text\":\"Hello\"}]}}}"
}VoiceId here is a placeholder โ once references is present, the reference audio determines the voice.
Voice cloning CloneVoice โ
{
"AudioData": "base64-encoded audio",
"ExtParam": "{\"engine\":\"tts-f\"}"
}The returned VoiceId can then be reused across TextToSpeech / TextToSpeechAsync calls.
Async synthesis and querying โ
For long text, submit via TextToSpeechAsync โ ExtParam is written exactly as for the sync API โ and it returns a TaskId. Poll Status with DescribeTextToSpeechAsyncTask and fetch the audio from AudioUrl once it completes.
Supported languages โ
24 in total:
| Language | Language |
|---|---|
| Arabic | Japanese |
| Cantonese | Korean |
| Chinese (Mandarin) | Polish |
| Czech | Portuguese |
| Dutch | Romanian |
| English | Russian |
| Finnish | Spanish |
| French | Thai |
| German | Turkish |
| Greek | Ukrainian |
| Hindi | Vietnamese |
| Indonesian |
Published prices โ
| Model type | Model | Price |
|---|---|---|
| TTS | s2-pro | $15.00 per million UTF-8 bytes |
| TTS | s1 | $15.00 per million UTF-8 bytes |
The default model s2.1-pro is not in the price list
The guide's price table only covers s2-pro and s1. The default model tts-f-s2.1-pro has no published price, and omitting model selects it โ confirm the billing basis before running batch jobs.
Limits and gotchas โ
- Emotion comes from body tags, not parameters: the tag goes at the start of
Text; there is noemotionfield inExtParam. referencesoutranksVoiceId: this is the sole exception to the "outer layer wins" rule โ once reference audio is present, the outer voice is ignored.- Use 10โ30 seconds of clear speech for reference audio, and make sure
references[].textmatches the audio exactly โ an inaccurate transcript directly degrades clone quality. - Base64 reference audio is bounded by the request body:
audio_datarequires the whole request to stay under 10 MB; useaudio_urlfor larger material. ExtParamis a string: it must be an escaped JSON string in the request; passing an object is rejected as a parameter error.enginematches exactly: writetts-fwith no surrounding whitespace.- Default sample rate is
16000: specify44100explicitly for high-fidelity work. Note thattts-fsample rates do not include48000(TTS-Seed does). - Volume is a half-open interval
(0, 10]:0is invalid; the minimum must be greater than 0. - The default model has no published price: see the section above.
- โณ entries need a real call to confirm: the โ
/ โณ marks on this page reflect what the TTS-F Engine Integration Guide enumerates; an API that is not listed (including
DescribeVoices) is not necessarily unavailable.
Related documents โ
| Document | Notes |
|---|---|
| MPS TTS Engines Compared | Capabilities, parameters and selection guidance across all seven 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-Index | The same APIs on IndexTTS (index-tts): a reference audio URL straight in VoiceId, 8-dimension emotion vector |
| 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 reference index |