Qwen-Audio-TTS HTTP Python SDK

Prerequisites

Obtain an API key completed, and API key configured as an environment variable.
DashScope Python SDK 1.25.17 or later installed. Install the latest version.

HttpSpeechSynthesizer class

Package path: dashscope.audio.http_tts.http_speech_synthesizer.HttpSpeechSynthesizer Description: HTTP-based speech synthesis. Use the stream parameter to switch between non-streaming and streaming modes.

call() — speech synthesis

Method signature:

@classmethod
def call(cls, model: str, text: str, voice: str,
         format: str = "wav", sample_rate: int = 24000,
         volume: int = 50, rate: float = 1.0, pitch: float = 1.0,
         bit_rate: int = 32, enable_ssml: bool = False,
         word_timestamp_enabled: bool = False,
         seed: int = 0, language_hints: list = None,
         instruction: str = None,
         enable_aigc_tag: bool = False,
         aigc_propagator: str = None,
         aigc_propagate_id: str = None,
         hot_fix: dict = None,
         stream: bool = False,
         api_key: str = None, **kwargs)

Parameters:

Parameter	Type	Required	Description
`model`	`str`	Yes	The speech synthesis model.
`text`	`str`	Yes	The text to synthesize. Supports SSML and LaTeX input. Replace the text content with the corresponding format. To use SSML, set `enable_ssml` to `True`. For supported SSML tags and usage, see SSML. To use LaTeX, replace the text with LaTeX format. No additional configuration is required. For supported LaTeX syntax and usage, see Convert LaTeX formulas to speech (Chinese language only).
`voice`	`str`	Yes	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`	`str`	No	The audio format. Default value: mp3. Valid values: mp3 pcm wav opus
`sample_rate`	`int`	No	The audio sample rate in Hz. Valid values: 8000, 16000, 22050 (default), 24000, 44100, 48000.
`volume`	`int`	No	The volume level. Default value: 50. Valid values: [0, 100].
`rate`	`float`	No	The speech rate. Default value: 1.0. Valid values: [0.5, 2.0].
`pitch`	`float`	No	The pitch. Default value: 1.0. Valid values: [0.5, 2.0].
`bit_rate`	`int`	No	The audio bitrate in kbps. Default value: 32. Valid values: [6, 510]. Tip: This parameter is supported only when `format` is set to `opus`.
`enable_ssml`	`bool`	No	Specifies whether to enable SSML. Set this to `True` when `text` uses SSML format. Default: `False`. For supported SSML tags and usage, see SSML. For the SSML usage restrictions (supported models, voices, and APIs), see Limitations.
`word_timestamp_enabled`	`bool`	No	Specifies whether to enable word-level timestamps. Default: False. True: Enabled. False: Disabled. Available only in streaming output mode. Cloned voices are supported. For supported system voices, see Qwen-Audio-TTS voice list.
`seed`	`int`	No	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`	`list`	No	Tip: - 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 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`	`str`	No	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`	`bool`	No	Specifies whether to embed an AIGC watermark in the generated audio. When set to True, a watermark is embedded in audio files of supported formats (wav/mp3/opus). Default: False.
`aigc_propagator`	`str`	No	Sets the `ContentPropagator` field in the AIGC watermark to identify the content distributor. Takes effect only when `enable_aigc_tag` is `True`. Default: QwenCloud account ID.
`aigc_propagate_id`	`str`	No	Sets the `PropagateID` field in the AIGC watermark to uniquely identify a specific distribution action. Takes effect only when `enable_aigc_tag` is `True`. Default: The request ID of the current speech synthesis request.
`hot_fix`	`dict`	No	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: See Example 1 below
`stream`	`bool`	No	Specifies whether to enable streaming mode. When set to `False` (non-streaming), the method returns a result object containing the audio URL. When set to `True` (streaming), the method returns an iterator that yields audio data chunks. Default: `False`.
`api_key`	`str`	No	The API key. If not specified, the SDK automatically reads from the `DASHSCOPE_API_KEY` environment variable.

Example 1 (Description):

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

Return values:

Non-streaming mode (stream=False): Returns a result object with the following properties:
- audio_url: The audio download URL (expires after a limited time).
- audio_id: The audio ID.
- expires_at: The URL expiration time.
Streaming mode (stream=True): Returns an iterator. Each element contains the following properties:
- audio_data: The audio binary data (bytes) for the current chunk.
- sentences: Sentence-level synthesis information (if available).

In streaming mode, the last element of the iterator contains both an audio data chunk and an audio_url field (the download URL for the complete audio). To avoid duplicating audio content when concatenating chunks, filter out this element by checking the not chunk.audio_url condition during iteration.

Sample code

The following examples show non-streaming and streaming calls to Qwen-Audio-TTS speech synthesis. Set the DASHSCOPE_API_KEY environment variable before running the code.

Use a voice that matches the model and supports the target language. When switching models, update the voice accordingly. See Qwen-Audio-TTS voice list.

Non-streaming call
Streaming call

A non-streaming call sets stream=False, waits for synthesis to complete, and returns an audio URL. Download the audio file from this URL.

# -*- coding: utf-8 -*-
import os
import dashscope
from dashscope.audio.http_tts.http_speech_synthesizer import HttpSpeechSynthesizer

# If the environment variable is not configured, replace the next line with: api_key = "sk-xxx", i.e., replace with your actual API Key
api_key = os.getenv("DASHSCOPE_API_KEY")
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
dashscope.base_http_api_url = 'https://ap-southeast-1.maas.qwencloudapi.com/api/v1'

# Non-streaming call, returns an audio URL
result = HttpSpeechSynthesizer.call(
    model="qwen-audio-3.1-tts-flash",  # When switching models, you must also switch to the corresponding voice for that version
    text="Today is a great day to build products that people love!",
    voice="longanhuan_v3.1",
    format="wav",
    sample_rate=24000,
    stream=False,
    api_key=api_key,
)

# Get the audio URL
print(f"Audio URL: {result.audio_url}")
print(f"Audio ID: {result.audio_id}")
if result.audio_id:
    request_id = result.audio_id.removeprefix("audio_")
    print(f"Request ID: {request_id}")
print(f"Expiration time: {result.expires_at}")

A streaming call sets stream=True and returns an iterator that yields audio data in chunks, enabling real-time playback with low first-packet latency. The last element of the iterator also returns a complete audio_url. When iterating, use not chunk.audio_url to filter out this element and avoid duplicating audio content.

# -*- coding: utf-8 -*-
import os
import dashscope
from dashscope.audio.http_tts.http_speech_synthesizer import HttpSpeechSynthesizer

# If the environment variable is not configured, replace the next line with: api_key = "sk-xxx", i.e., replace with your actual API Key
api_key = os.getenv("DASHSCOPE_API_KEY")
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
dashscope.base_http_api_url = 'https://ap-southeast-1.maas.qwencloudapi.com/api/v1'

# Streaming call, returns audio data chunk by chunk
stream_result = HttpSpeechSynthesizer.call(
    model="qwen-audio-3.1-tts-flash",  # When switching models, you must also switch to the corresponding voice for that version
    text="Today is a great day to build products that people love!",
    voice="longanhuan_v3.1",
    format="wav",
    sample_rate=24000,
    stream=True,
    api_key=api_key,
)

# Iterate over the iterator, receiving audio data chunk by chunk
audio_chunks = []
for chunk in stream_result:
    if not chunk.audio_url and chunk.audio_data:  # Filter out the last chunk containing the full audio URL to avoid audio duplication
        audio_chunks.append(chunk.audio_data)
        print(f"Received audio data chunk, size: {len(chunk.audio_data)} bytes")

    if chunk.sentences:
        print(f"Sentence info: {chunk.sentences}")

    if chunk.audio_id:
        print(f"Audio ID: {chunk.audio_id}")
        request_id = chunk.audio_id.removeprefix("audio_")
        print(f"Request ID: {request_id}")

# Merge all audio data and save
full_audio = b"".join(audio_chunks)
print(f"Total audio size: {len(full_audio)} bytes")

with open("output.wav", "wb") as f:
    f.write(full_audio)
print("Audio saved to output.wav")

​Prerequisites

​HttpSpeechSynthesizer class

​call() — speech synthesis

​Sample code

Prerequisites

HttpSpeechSynthesizer class

call() — speech synthesis

Sample code