Qwen-Audio-TTS non-real-time speech synthesis HTTP API reference

The features described in this document are available only in the China (Beijing) region.

Alibaba Cloud Model Studio has released a workspace-specific domain for the China (Beijing) region. The new dedicated domain delivers superior performance and higher stability for inference requests. We recommend migrating from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com.

Endpoint

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer Replace {WorkspaceId} with your actual workspace ID.

Request headers

Parameter	Type	Required	Description
Authorization	`string`	Yes	Authentication token in the format `Bearer <your_api_key>`. Replace `<your_api_key>` with your actual API key.
Content-Type	`string`	Yes	Media type of the request body. Fixed to `application/json`.
X-DashScope-SSE	`string`	No	Enables streaming mode for the response. Required for streaming synthesis. Set to `enable`.

Request body

model string(required)The speech synthesis model.input object(required)The input parameter object.

Properties

text string(required)The text to synthesize.SSML and LaTeX format inputs are supported. Replace the text content with the corresponding format.

To use SSML, set enable_ssml to true. For supported SSML tags, see SSML.
To use LaTeX, replace the text content with LaTeX format. No additional configuration is required. For supported LaTeX syntax, see Convert LaTeX formulas to speech (Chinese language only).

voice string(required)The voice for synthesis.Valid values:

System voices: See Qwen-Audio-TTS voice list
Voice cloning voices: To create a voice, see Voice cloning HTTP API reference
Voice design voices: To create a voice, see Voice Design API reference

format string(optional)The audio format.Default value: mp3.Valid values:

mp3
pcm
wav
opus

sample_rate integer(optional)The audio sample rate in Hz.Valid values: 8000, 12000, 16000, 22050 (default), 24000, 44100, 48000.

When format is opus, sample_rate supports only 8000, 12000, 16000, 24000, and 48000.

volume integer(optional)The volume level.Default value: 50.Valid values: [0, 100].rate float(optional)The speech rate.Default value: 1.0.Valid values: [0.5, 2.0].bit_rate integer(optional)The audio bitrate in kbps.Default value: 32.Valid values: [6, 510].

This parameter is supported only when format is set to opus.

pitch float(optional)The pitch.Default value: 1.0.Valid values: [0.5, 2.0].enable_ssml boolean(optional)Specifies whether to enable SSML. For the SSML usage restrictions (supported models, voices, and APIs), see Limitations.word_timestamp_enabled boolean(optional)Specifies whether to enable word-level timestamps.Default value: false.Available only in streaming output mode. Cloned voices are supported. For supported system voices, see Qwen-Audio-TTS voice list.seed integer(optional)The random seed for synthesis. Different seeds produce different outputs. With identical model version, text, voice, and other parameters, the same seed reproduces the same output.Default value: 0.Valid values: [0, 65535].language_hints array[string](optional)

This parameter is an array, but the current version processes only the first element. Pass a single value.
This parameter specifies the target language for speech synthesis and is unrelated to the language of the sample audio used in voice cloning. To set the source language for a voice cloning task, see the Voice Cloning API reference.

Specifies the target language for speech synthesis to improve output quality.Use this parameter when numbers, abbreviations, or symbols are not pronounced as expected, or when synthesis quality for secondary languages is poor. Examples:

A number isn't read as expected: "hello, this is 110" is read as "hello, this is one one zero" instead of "hello, this is yao-yao-ling"
A symbol isn't read correctly: "@" is read as "ai-te" instead of "at"
Minor language synthesis sounds unnatural

Valid values

zh: Chinese
en: English
fr: French
de: German
ja: Japanese
ko: Korean
ru: Russian
pt: Portuguese
th: Thai
id: Indonesian
vi: Vietnamese
es: Spanish
it: Italian
ms: Malaysian
fil: Filipino
ar: Arabic

instruction string(optional)An instruction that controls the synthesis behavior, such as dialect, emotion, or role.For usage details, see Non-real-time speech synthesis.enable_aigc_tag boolean(optional)Specifies whether to embed an AIGC watermark in the generated audio. When set to true, the watermark is embedded in audio files of supported formats (wav/mp3/opus).Default value: false.aigc_propagator string(optional)Sets the ContentPropagator field in the AIGC watermark, identifying the content propagator. Takes effect only when enable_aigc_tag is true.Default value: Alibaba Cloud UID.aigc_propagate_id string(optional)Sets the PropagateID field in the AIGC watermark, uniquely identifying a specific propagation action. Takes effect only when enable_aigc_tag is true.Default value: The request ID of the current speech synthesis request.hot_fix object(optional)Text hot-fix configuration. Customizes the pronunciation of specified words or substitutes text before speech synthesis.Parameters:

pronunciation: Custom pronunciation. Provides pinyin for given words to correct cases where the default pronunciation is inaccurate.
replace: Text substitution. Replaces specified words with target text before speech synthesis; the substituted text is what gets synthesized.

Example:

"hot_fix": {
  "pronunciation": [
    {"weather": "tian1 qi4"}
  ],
  "replace": [
    {"today": "gold day"}
  ]
}

curl -X POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-audio-3.0-tts-flash",
    "input": {
      "text": "There is a very large garden behind my house.",
      "voice": "longanhuan_v3.6",
      "format": "wav",
      "sample_rate": 24000
    }
}'

Response body

request_id stringThe unique identifier of this request.output objectThe data returned by the model.

Properties

finish_reason stringIndicates why synthesis stopped. The value is stop when synthesis completes normally.Valid values:

null: Synthesis in progress
stop: Synthesis completed

type stringThe sub-event type. Returned only in streaming mode.Valid values:

sentence-begin: Marks the beginning of a sentence and returns the text content to synthesize
sentence-synthesis: Marks an audio data chunk
- Multiple sentence-synthesis events are emitted during the synthesis of a single sentence, each carrying one audio data chunk
- The client must receive these audio data chunks in order and write them to the same file in append mode
- Each sentence-synthesis event maps one-to-one to its subsequent audio data frame
sentence-end: Marks the end of a sentence and returns the sentence text and usage information (usage)

original_text stringA sentence extracted from the segmented input text. May be absent for the last sentence.sentence objectSentence information.

Properties

index integerThe sentence index, starting from 0.words arrayWord-level information for the sentence.

Properties

text stringThe word or character.begin_index integerThe start position index of the word within the sentence, starting from 0.end_index integerThe end position index of the word within the sentence, starting from 1.begin_time integerThe start timestamp of the word in the audio, in milliseconds.end_time integerThe end timestamp of the word in the audio, in milliseconds.

audio objectThe synthesized audio data.

Properties

data stringBase64-encoded audio data in streaming mode. Empty in non-streaming mode.url stringThe URL of the complete audio file generated by the model. Expires after 24 hours.id stringThe ID of the audio output from the model.expires_at integerThe expiration timestamp of the url.

usage objectBilling usage.

Properties

input_tokens integerInput token count for this request.

Applies to qwen-audio-3.1-tts-flash.

output_tokens integerOutput token count for this request.

Applies to qwen-audio-3.1-tts-flash.

total_tokens integerSum of input and output tokens.

Applies to qwen-audio-3.1-tts-flash.

characters integerCumulative number of billed characters.

Applies to qwen-audio-3.0-tts-plus and qwen-audio-3.0-tts-flash.

Non-streaming
Streaming

{
    "request_id": "ee88b03d-0457-9286-8c67-xxxxxxxxxxxx",
    "output": {
        "finish_reason": "stop",
        "audio": {
            "data": "",
            "url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/qwen-audio-3.0-tts-flash/20260304/xxxxxxxx/ee88b03d-0457-9286-8c67-xxxxxxxxxxxx.wav?xxxxxxx",
            "id": "audio_ee88b03d-0457-9286-8c67-xxxxxxxxxxxx",
            "expires_at": 1772697707
        }
    },
    "usage": {
        "characters": 15
    }
}

Intermediate result:

{
    "request_id": "8ac1cd04-06af-9a63-b031-xxxxxxxxxxxx",
    "output": {
        "finish_reason": "null",
        "type": "sentence-begin",
        "original_text": "There is a very large garden behind my house.",
        "sentence": {
            "index": 0,
            "words": []
        },
        "audio": {
            "data": "",
            "id": "audio_ee88b03d-0457-9286-8c67-xxxxxxxxxxxx",
            "expires_at": 1772697707
        }
    },
    "usage": {
        "characters": 15
    }
}

Final result:

{
    "request_id": "8ac1cd04-06af-9a63-b031-xxxxxxxxxxxx",
    "output": {
        "finish_reason": "stop",
        "audio": {
            "data": "",
            "url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/qwen-audio-3.0-tts-flash/20260304/xxxxxxxx/8ac1cd04-06af-9a63-b031-xxxxxxxxxxxx.wav?xxxxxxx",
            "id": "audio_8ac1cd04-06af-9a63-b031-xxxxxxxxxxxx",
            "expires_at": 1772698611
        }
    },
    "usage": {
        "characters": 15
    }
}

​Endpoint

​Request headers

Request body

Response body

Endpoint

Request headers