Non-real-time speech synthesis Qwen-Audio-TTS/CosyVoice Python SDK reference

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,
         enable_markdown_filter: bool = False,
         stream: bool = False,
         api_key: str = None, **kwargs)

Parameters:

"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).

  Important

  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.

Non-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")
# Replace "{WorkspaceId}" with your actual Workspace ID
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

# Non-streaming call, returns an audio URL
result = HttpSpeechSynthesizer.call(
    model="qwen-audio-3.0-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.6",  # This voice is for qwen-audio-3.0-tts-flash; for qwen-audio-3.0-tts-plus, use longanlingxin or longanlufeng; for the cosyvoice-v3 series, use longanhuan; for cosyvoice-v2, use v2 voices such as longxiaochun_v2
    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}")

Streaming call

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")
# Replace "{WorkspaceId}" with your actual Workspace ID
dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

# Streaming call, returns audio data chunk by chunk
stream_result = HttpSpeechSynthesizer.call(
    model="qwen-audio-3.0-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.6",  # This voice is for qwen-audio-3.0-tts-flash; for qwen-audio-3.0-tts-plus, use longanlingxin or longanlufeng; for the cosyvoice-v3 series, use longanhuan; for cosyvoice-v2, use v2 voices such as longxiaochun_v2
    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")