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,
))
import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor
import dashscope
text_to_synthesize = [
'This is the first sentence.',
'This is the second sentence.',
'This is the third sentence.',
]
# 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='commit'
)
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, session)
for text in text_to_synthesize:
print(f'send text: {text}')
session.send_event({'type': 'input_text_buffer.append', 'text': text})
# In commit mode, the client triggers synthesis explicitly
session.send_event({'type': 'input_text_buffer.commit'})
time.sleep(0.1)
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 |
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
|
mode | str | No | The interaction mode. Valid values:
|
response_format | str | No | The format of the audio output from the model. Supported formats:
|
sample_rate | int | No | The sample rate of the audio output from the model, in Hz. Supported sample rates:
|
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 ( 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 signature | Server response events (delivered via | Description |
|---|---|---|
|
| Connect to the server. Automatically called when entering the |
|
| 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. |
| None | Send a raw event. Text input is handled through the
|
|
| Send the |
|
| Send the
|
|
| Send the session.finish event to terminate the task. Then keep consuming |
| None | Close the connection. Automatically called when exiting the |
| None | Get the session_id of the current task. |
| None | Get the response_id of the most recent response. |
| None | Get 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.
Method | Parameters | Return value | Description |
|---|---|---|---|
| event: Server response event ( | Iterator | Includes API call responses and model-generated text and audio. Iteration ends after the |
| event: Server response event ( | Event or | Read one server event. Returns |