Skip to main content
SDK access

Python SDK

Real-time TTS Python SDK

Supported regions: Singapore and China North 2 (Beijing). Use an API key and endpoint from the region you call; see Regions and endpoints. This topic describes the key interfaces and request parameters for calling Qwen-TTS-Realtime models with the DashScope Python SDK.

Prerequisites

Requires DashScope Python SDK 2.0.1 or later.

Getting started

import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor

import dashscope

text_to_synthesize = [
    'Right? I love supermarkets like this.',
    'Especially during Chinese New Year,',
    'I go shopping at supermarkets.',
    'And I feel',
    'absolutely thrilled!',
    'I want to buy so many things!'
]

# If you have not configured the API key in an environment variable, replace the following line with your own API key: api_key="sk-xxx"
client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# Receiving thread: iterate over the server events and write the audio to the file incrementally
def receive_events(session):
    with open('result_24k.pcm', 'wb') as f:
        for event in session.events():
            event_type = event.get('type')
            if event_type == 'session.created':
                print('start session: {}'.format(event['session']['id']))
            elif event_type == 'response.audio.delta':
                f.write(base64.b64decode(event['delta']))
            elif event_type == 'response.done':
                print(f'response {session.last_response_id} done')
            elif event_type == 'session.finished':
                print('session finished')

if __name__  == '__main__':
    print('Initializing ...')

    # Create a real-time speech synthesis session: entering the with context automatically establishes the connection
    with client.audio.realtime.connect(
            model='qwen3-tts-flash-realtime',
            # 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
            ws_url='wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime',
    ) as session:
        session.update_session(
            output_modalities=['audio'],
            voice='Cherry',
            response_format='pcm',
            sample_rate=24000,
            mode='server_commit'
        )
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, session)
            for text_chunk in text_to_synthesize:
                print(f'send text: {text_chunk}')
                session.send_event({'type': 'input_text_buffer.append', 'text': text_chunk})
                time.sleep(0.1)
            # Notify the server that the input is complete (in server_commit mode the server decides when to synthesize)
            session.end_session()
            receiver.result()
        print('[Metric] session: {}, first audio delay: {}'.format(
            session.session_id,
            session.last_first_audio_delay,
        ))
Visit GitHub to download more sample code.

Request parameters

Set these parameters in the connect method of client.audio.realtime:

Parameter

Type

Required

Description

model

str

Yes

Model name (see Supported models).

ws_url

str

No

Session endpoint. Pass wss//ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime (Singapore). For another region, replace ap-southeast-1 in the URL. See Regions and endpoints.

Configure these parameters using the update_session method of the session (named parameters are passed directly, and other parameters are passed through to the session object in the session.update event):

Parameter

Type

Required

Description

voice

str

Yes

The voice for speech synthesis. For more information, see Supported voices.

System voices and custom voices are supported:

  • System voices: Available only for the Qwen3-TTS-Instruct-Flash-Realtime, Qwen3-TTS-Flash-Realtime, and Qwen-TTS-Realtime model series. For voice samples, see Supported voices.

  • Custom voices

    • Voices customized by the Voice Cloning (Qwen) feature: Available only for the Qwen3-TTS-VC-Realtime model series.

    • Voices customized by the Voice Design (Qwen) feature: Available only for the Qwen3-TTS-VD-Realtime model series.

language_type

str

No

Specifies the language of the synthesized audio. The default value is Auto.

  • Auto: Use this value when the language of the text is uncertain or contains multiple languages. The model automatically matches the pronunciation for different language segments in the text, but cannot guarantee perfect accuracy.

  • Specific language: Use this for single-language text. Specifying a language significantly improves synthesis quality and typically yields better results than Auto. Valid values include the following:

    • Chinese

    • English

    • German

    • Italian

    • Portuguese

    • Spanish

    • Japanese

    • Korean

    • French

    • Russian

mode

str

No

The interaction mode. Valid values:

  • server_commit (default): The server automatically determines when to synthesize speech, balancing latency and quality. This mode is recommended for most scenarios.

  • commit: The client manually triggers synthesis. This mode has the lowest latency, but you must manage sentence integrity yourself.

response_format

str

No

The format of the audio output from the model.

Supported formats:

  • pcm (default)

  • wav

  • mp3

  • opus

sample_rate

int

No

The sample rate of the audio output from the model, in Hz.

Supported sample rates:

  • 8000

  • 16000

  • 24000 (default)

  • 48000

speech_rate

float

No

The speech rate of the audio. A value of 1.0 is the normal speed. A value less than 1.0 is slower, and a value greater than 1.0 is faster.

Default value: 1.0.

Valid range: [0.5, 2.0].

volume

int

No

The volume of the audio.

Valid range: [0, 100].

pitch_rate

float

No

The pitch of the synthesized audio.

Default value: 1.0.

Valid range: [0.5, 2.0].

bit_rate

int

No

Specifies the bitrate of the audio in kbps. A higher bitrate results in better audio quality and a larger file size. This parameter is available only when the audio format (response_format) is set to opus.

Default value: 128.

Valid range: [6, 510].

Key interfaces

Session (RealtimeSession)

A real-time speech synthesis session is created by client.audio.realtime.connect(model=...). The connection is automatically established when entering the with context (or you can call the session's connect() method manually).
Method signatureServer response events (delivered via events() iteration)Description
def connect(self) -> "RealtimeSession"
session.created
Session created
session.updated
Session configuration updated
Connect to the server. Automatically called when entering the with context.
def update_session(self,
                   output_modalities: List[str],
                   *,
                   voice: str = None,
                   **kwargs) -> None
session.updated
Session configuration updated
Update default session configurations. For parameter details, see the Request parameters.After connecting, the server returns default input and output configurations. Call this method immediately after connecting to update these defaults.The server validates parameters when it receives a session.update event. If validation fails, it returns an error; otherwise, it updates the session configuration.
def send_event(self,
               event: Dict[str, Any]) -> None
NoneSend a raw event. Text input is performed with the input_text_buffer family of events: append a text chunk to the cloud input buffer ({"type": "input_text_buffer.append", "text": ...}). The buffer is temporary storage for text that you write to and submit later.
  • In server_commit mode, the server decides when to submit and synthesize text in the buffer.
  • In commit mode, the client must send the input_text_buffer.commit event to trigger speech synthesis.
def send_event(self,
               event: Dict[str, Any]) -> None
input_text_buffer.cleared
Clear text received by the server
Send the {"type": "input_text_buffer.clear"} event to delete all text in the cloud buffer.
def send_event(self,
               event: Dict[str, Any]) -> None
input_text_buffer.committed
Submit text and trigger speech synthesis
response.output_item.added
New output content added
response.content_part.added
New content added to assistant message
response.audio.delta
Incremental audio generated by the model
response.audio.done
Audio generation completed
response.content_part.done
Streaming of audio content for assistant message completed
response.output_item.done
Streaming of entire output item for assistant message completed
response.done
Response completed
Send the {"type": "input_text_buffer.commit"} event to submit all text previously appended to the cloud buffer and synthesize it immediately. Returns an error if the buffer is empty.
  • In server_commit mode, clients do not need to send this event. The server submits the buffer automatically.
  • In commit mode, clients must trigger speech synthesis with commit.
def end_session(self) -> None
session.finished
Response completed
Send the session.finish event to terminate the task. Keep consuming events() afterwards until the session.finished event.
def close(self, ) -> None
NoneClose the connection. Automatically called when exiting the with context.
session.session_id
NoneGet the session ID for the current task.
session.last_response_id
NoneGet the response ID of the most recent response.
session.last_first_audio_delay
NoneGet the delay before the first audio packet arrives.

Event iteration (events())

The server returns response events and data as events. Iterate the session's events() in the receiving thread to handle server events; iteration ends after the session.finished event. error events are raised as DashScopeError exceptions, which you can catch with try/except.
MethodParametersReturn valueDescription
def events(self) -> Iterator[Dict]
event: server response event (dict).IteratorIncludes API call responses and model-generated text and audio. Iteration ends after the session.finished event. For more information, see Server events.
def recv_event(self) -> Optional[Dict]
event: server response event (dict).Event or NoneRead one server event. Returns None after a normal close.