Call Qwen real-time speech synthesis using Python SDK - Alibaba Cloud Model Studio - Alibaba Cloud_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

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

Server commit mode

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 API Key differs between the Singapore and Beijing regions. Get your API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the configuration for the Singapore (ap-southeast-1) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ by region.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# 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',
    ) 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,
        ))

Commit mode

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 API Key differs between the Singapore and Beijing regions. Get your API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following is the configuration for the Singapore (ap-southeast-1) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ by region.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# 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',
    ) 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 the synthesis
                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

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

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

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 signature	Server 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`	None	Send 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`	None	Close the connection. Automatically called when exiting the `with` context.
`session.session_id`	None	Get the session ID for the current task.
`session.last_response_id`	None	Get the response ID of the most recent response.
`session.last_first_audio_delay`	None	Get 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.

Method	Parameters	Return value	Description
`def events(self) -> Iterator[Dict]`	event: server response event (`dict`).	Iterator	Includes 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 `None`	Read one server event. Returns `None` after a normal close.