Skip to content

TTS-Fishaudio โ€‹

Updated

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:

  1. Emotion lives in the text body, not in a separate parameter โ€” you prepend a tag such as [excited] to Text, and tag content can be customised.
  2. Zero-shot cloning can be done inline โ€” pass a reference clip in engineCustom.references and that request is synthesised in that voice, without calling CloneVoice first to obtain a VoiceId.
  3. LLM-style sampling controls โ€” temperature / top_p / repetition_penalty tune expressiveness and repetition, while latency picks 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:

APIWhat it doesModeOfficial reference
TextToSpeechShort text to speech, returns audio directlySync1041/82311
CloneVoiceClone a voice from reference audio, returns a reusable VoiceIdSync1041/82312
TextToSpeechAsyncLong text to speech, returns a TaskIdAsync1041/79693
DescribeTextToSpeechAsyncTaskQuery async synthesis result (Status / AudioUrl)Sync1041/79696

Other APIs in the same group โ€‹

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

LayerPurposeNotes
enginePick the engineAlways tts-f on this page
synExt.*Synthesis parameters normalised by MPSModel, format, sample rate, duration, speed, volume
synExt.engineCustom.*Parameters passed through to Fish AudioReference 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 โ€‹

ParameterTypeRequiredDescription
engineStringYesSet to tts-f
synExtObjectNoSpeech-synthesis extension parameters
synExt.modelStringNoModel: tts-f-s2.1-pro (default), tts-f-s2-pro, tts-f-s1
synExt.formatStringNoOutput audio format: wav, mp3, opus. Default wav
synExt.sampleRateIntegerNoSample rate: 8000, 16000, 22050, 24000, 32000, 44100. Default 16000
synExt.durationFloatNoTarget audio duration
synExt.speedFloatNoSpeaking rate, range [0.5, 2], default 1.0
synExt.volFloatNoVolume, range (0, 10], default 1.0
synExt.engineCustomObjectNoEngine-specific parameters passed through to Fish Audio

Model list โ€‹

ValueNotes
tts-f-s2.1-proDefault model, current-generation Pro
tts-f-s2-proPrevious-generation Pro
tts-f-s1S1 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 โ€‹

ParameterTypeRequiredDescription
referencesArray of ObjectNoArray 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_dataStringNoReference audio as Base64 (request body must stay under 10 MB). Mutually exclusive with audio_url
references[].audio_urlStringNoReference 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[].textStringNoThe exact transcript of the sample audio. Accuracy is critical to clone quality
temperatureFloatNoControls expressiveness. Higher is more varied, lower is more stable. Range [0, 1], default 0.7
top_pFloatNoControls diversity via sampling. Range [0, 1], default 0.7
latencyStringNoQuality/latency trade-off: normal best quality / balanced reduced latency / low lowest latency. Default normal
repetition_penaltyIntegerNoPenalty 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):

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

text
[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:

EmotionTagToneTypical context
Happy[happy]Cheerful, upbeatGood news, greetings
Sad[sad]Melancholic, downcastSympathy, bad news
Angry[angry]Frustrated, aggressiveComplaints, warnings
Excited[excited]Energetic, enthusiasticAnnouncements, celebrations
Calm[calm]Peaceful, relaxedInstructions, meditation
Nervous[nervous]Anxious, uncertainDisclaimers, apologies
Confident[confident]Assertive, self-assuredPresentations, sales
Surprised[surprised]Shocked, amazedReactions, discoveries
Satisfied[satisfied]Content, pleasedConfirmations, reviews
Delighted[delighted]Very pleased, joyfulCelebrations, compliments
Scared[scared]Frightened, fearfulWarnings, horror stories
Worried[worried]Concerned, troubledConcerns, questions
Upset[upset]Disturbed, distressedComplaints, problems
Frustrated[frustrated]Annoyed, exasperatedTechnical issues, delays
Depressed[depressed]Very sad, hopelessSerious topics
Empathetic[empathetic]Understanding, caringSupport, counselling
Embarrassed[embarrassed]Ashamed, awkwardApologies, mistakes
Disgusted[disgusted]Repelled, revoltedNegative reviews
Moved[moved]Emotionally touchedHeartfelt moments
Proud[proud]Accomplished, satisfiedAchievements, praise
Relaxed[relaxed]At ease, casualCasual conversation
Grateful[grateful]Thankful, appreciativeThanks, appreciation
Curious[curious]Inquisitive, interestedQuestions, exploration
Sarcastic[sarcastic]Ironic, mockingHumour, 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:

ScenarioApproachVoiceId
The voice is reused often (e.g. a fixed presenter)Call CloneVoice once to create itUse the returned VoiceId, e.g. 7f92f8afb8ec43bf81429cc1c9199cb1
One-off, or very many distinct voicesPass engineCustom.references directlyCan 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 โ€‹

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

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

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

LanguageLanguage
ArabicJapanese
CantoneseKorean
Chinese (Mandarin)Polish
CzechPortuguese
DutchRomanian
EnglishRussian
FinnishSpanish
FrenchThai
GermanTurkish
GreekUkrainian
HindiVietnamese
Indonesian

Published prices โ€‹

Model typeModelPrice
TTSs2-pro$15.00 per million UTF-8 bytes
TTSs1$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 no emotion field in ExtParam.
  • references outranks VoiceId: 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[].text matches the audio exactly โ€” an inaccurate transcript directly degrades clone quality.
  • Base64 reference audio is bounded by the request body: audio_data requires the whole request to stay under 10 MB; use audio_url for larger material.
  • ExtParam is a string: it must be an escaped JSON string in the request; passing an object is rejected as a parameter error.
  • engine matches exactly: write tts-f with no surrounding whitespace.
  • Default sample rate is 16000: specify 44100 explicitly for high-fidelity work. Note that tts-f sample rates do not include 48000 (TTS-Seed does).
  • Volume is a half-open interval (0, 10]: 0 is 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.
DocumentNotes
MPS TTS Engines ComparedCapabilities, parameters and selection guidance across all seven 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-IndexThe same APIs on IndexTTS (index-tts): a reference audio URL straight in VoiceId, 8-dimension emotion vector
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 reference index

Built with VitePress ยท Deployed on Tencent EdgeOne Pages