TTS FAQ

Why does a WAV file show a different duration from its actual playback duration?

Standard TTS streams audio as it is synthesized. The WAV header contains estimated values, so the displayed file duration may differ from the actual playback duration. For example, a file may show a duration of 7 seconds while the speech lasts less than 5 seconds.

If an accurate duration is required, set format to pcm, receive the complete audio, and add a WAV header based on the actual audio data. For output format settings, see TTS API reference.

Why does the TTS response look garbled when read as text?

On success, the short-text TTS endpoint /stream/v1/tts returns binary audio, not text. Save or play the response in the audio format specified in the request instead of parsing it as a string.

The asynchronous long-text endpoint /rest/v1/tts/async returns a different response: obtain the task ID first, and then query the synthesis result for the audio URL. For the complete procedure, see Long-text TTS API reference.

Does the WeChat mini program SDK support streamed audio output?

Yes. The TTS interface in the WeChat mini program SDK returns binary audio chunks through data events and signals completion through a complete event. Submitting all input text at once does not mean that all audio is returned at once. Audio chunks can be processed as each data event arrives.

How can I read a number as a whole or digit by digit?

Use the SSML say-as tag to specify how a number is read. SSML is an XML-based speech synthesis markup language that controls sentence and word segmentation, pronunciation, speaking rate, pauses, pitch, and volume. It can also add background music. For tag usage, see SSML overview.

How is the pronunciation of a Chinese polyphonic character determined?

When a Chinese polyphonic character is not part of a phrase, TTS predicts its pronunciation from the context and selects one pronunciation.

How can I correct a mispronunciation or an unexpected reading of a Chinese polyphonic character?

Try replacing the polyphonic character with another Chinese character that has the intended pronunciation, or use SSML to control the pronunciation. SSML also controls sentence and word segmentation, speaking rate, pauses, pitch, and volume, and can add background music. For details, see SSML overview.

Can I change the speaking rate for only part of the text?

Yes. Use SSML to control the speaking rate for part of the text. For details, see SSML overview.

Do I need to set enable_ssml to use SSML with standard TTS?

The WebSocket SpeechSynthesizer interface does not require enable_ssml=true to use SSML. Submit the complete SSML document as the synthesis text and select a voice that supports the tags used.

For supported tags and voices, see SSML overview.

How are special symbols and punctuation handled?

Special symbols such as α, β, γ, ρ, sin, cos, and tan are pronounced. Percent signs are read as percentages, and colons and parentheses create pauses. Chinese book title marks and dashes are not currently recognized.

How accurate is TTS pronunciation?

TTS uses probabilistic models. Pronunciation accuracy in the industry ranges from 96% to 98%, and Intelligent Speech Interaction achieves approximately 97% accuracy in general-scenario tests. Not all pronunciation errors can be corrected. Try substituting characters or using SSML to adjust pronunciation.

What are TTS timestamps used for?

TTS can return the audio positions of Chinese characters or English words alongside the audio stream, for uses such as subtitle generation. Word-level timestamps and phoneme-level timestamps are separate features. Phoneme-level timestamps can drive virtual avatar lip movements; support depends on the voice.

begin_index and end_index are indexes of normalized text units, not character offsets that can be applied directly to the original input string. For field definitions and supported voices, see TTS timestamps.

Do SSML pauses affect subtitle timestamps?

Yes. When a <break> tag adds a pause, the subtitle timestamps for subsequent text shift with the pause in the audio. The pause is not subtracted from the timeline. Position subtitles using the returned audio timestamps rather than converting text indexes into playback times.

What are the limits for long-text TTS?

Long-text TTS converts long passages, such as thousands or tens of thousands of characters, into audio. It supports PCM, WAV, and MP3 output, settings for speaking rate, pitch, and volume, and male and female voices. Synthesis results can be obtained in real time or asynchronously.

Standard TTS supports text of fewer than 300 characters. Long-text TTS supports up to 100,000 characters in one request. For limits and usage, see Long-text TTS API reference.

Why is the text length limited per request?

Text length limits help avoid wasting server resources: audio synthesized from a large amount of text may not all be used. When calling an API or SDK, text can be synthesized in segments and the audio joined afterward.

MRCP is commonly used for customer service or call centers. Long, uninterrupted playback does not suit these interactions and is often interrupted or stopped early. For news articles containing thousands or tens of thousands of characters, long-text TTS supports up to 100,000 characters per request. For details, see Long-text TTS API reference.

Do I need a different Appkey to call CosyVoice?

An Appkey identifies a project; it is not a separate credential type for standard TTS or CosyVoice. The same project Appkey can call the corresponding activated services. To call CosyVoice, activate the appropriate service and use its protocol and voices. Do not reuse all request parameters from standard TTS unchanged.

How can I reduce the wait for synthesized audio?

Improvements in synthesis quality typically involve more complex algorithms and computation, so advanced voices may take longer to synthesize. Use streamed output to save or play audio as it arrives instead of waiting for the entire text to finish synthesizing.

Distinguish the time to synthesize the full text from first-packet latency. First-packet latency is the interval between the client finishing sending a synthesis request and first receiving binary audio from the server. Use this metric when assessing the wait before playback can begin. For the interface and parameters, see TTS API reference.

Why does synthesis latency vary by voice?

The real-time factor depends on the complexity of the model algorithm. The fastest model can synthesize 33 seconds of audio in 1 second; the slowest can synthesize 0.7 seconds of audio in 1 second. Standard and premium voices have different latencies. Voices with better algorithmic quality take relatively longer to synthesize.

How do I resolve Missing message appkey?

Gateway:MESSAGE_INVALID:Missing message appkey with error code 40000002 means that the request is missing appkey. Check that the request actually sent contains the project Appkey and that the application has loaded the corresponding configuration.

This differs from 40020105 APPKEY_NOT_EXIST, which means that the supplied Appkey does not exist. For that error, check that the correct project Appkey was entered.

How can I avoid directive errors and idle timeouts in streaming-text TTS?

Use the following sequence with FlowingSpeechSynthesizer:

1. Send StartSynthesis and wait for the server to return SynthesisStarted.

2. Send text with RunSynthesis.

3. After sending all text, send StopSynthesis to synthesize the remaining text and end the task. The end directive is not lowercase stop.

Send text promptly after receiving SynthesisStarted. If the first text segment is not sent within approximately 10 seconds, 40000004 IDLE_TIMEOUT is triggered. Do not use punctuation at the end of the text as a substitute for StopSynthesis. Use this directive to end input even if the remaining text has no punctuation.