Skip to main content

Python SDK

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.

Quick start

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!'
]

# The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. Regions differ in configuration.
client = dashscope.Client(
    # API keys differ between the Singapore and Beijing regions. Get an API key: https://help.aliyun.com/en/model-studio/get-api-key
    # If the API key is not configured as an environment variable, replace the next line with your API key: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# Receiver thread: iterate server events and write audio data to a 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: the connection is established automatically when entering the with context
    with client.audio.realtime.connect(
            model='qwen3-tts-flash-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

The following request parameters can be set with 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. If omitted, it is derived automatically from the Client constructor parameters workspace/region (China (Beijing) region: wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime; Singapore region: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime).

Configure the following parameters with the session's update_session method (named parameters are passed directly; other parameters are passed through to the session object of the session.update event).

Parameter

Type

Required

Description

voice

str

Yes

The voice for speech synthesis. For more information, see Qwen-TTS voice list.

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].

API reference

Session (RealtimeSession)

A real-time speech synthesis session is created with client.audio.realtime.connect(model=...). The connection is established automatically when entering the with context (or manually by calling the session's connect() method).
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 handled through the input_text_buffer family of events: append text chunks to the cloud input text buffer ({"type": "input_text_buffer.append", "text": ...}). The buffer is temporary storage that you can write to and commit later.
  • In "server_commit" mode, the server decides when to submit and synthesize the 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 the text in the current 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 commit the text previously appended to the cloud buffer and synthesize it immediately. An error occurs if the input text 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 via commit.
def end_session(self) -> None
session.finished
Response completed
Send the session.finish event to terminate the task. Then keep consuming events() 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 of 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 to the client as events. Iterate the session's events() in a receiver 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 details, 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.