time speech synthesis API reference (Qwen-TTS-Realtime)-Interaction flow for real-time speech synthesis

Connect to the Qwen-TTS real-time speech synthesis service over a WebSocket connection. This page covers the service endpoint, request headers, and interaction flow. For model overview and selection guidance, see Real-time speech synthesis

The Qwen-TTS Realtime API uses the WebSocket protocol. For Java and Python, use the DashScope SDK to avoid handling WebSocket details directly. For other languages, connect using a WebSocket library.

Service endpoint

The WebSocket URL is as follows. Specify the model name using the model query parameter:

International

WebSocket URL: wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime?model=qwen3-tts-flash-realtime

Chinese mainland

WebSocket URL: wss://dashscope.aliyuncs.com/api-ws/v1/realtime?model=qwen3-tts-flash-realtimeImportant

The URL must use the wss:// protocol. Set the Authorization header (see Request headers) and specify the model using the model query parameter.

Request headers

Include the following headers in the request:

Parameter	Type	Required	Description
Authorization	string	Yes	Authentication token in the format Bearer . Replace with your actual API key.
user-agent	string	No	Client identifier for server-side source tracking.
X-DashScope-WorkSpace	string	No	The Alibaba Cloud Model Studio workspace ID.

Important

Authorization is verified during the WebSocket handshake. If the API key is invalid or missing, the handshake fails with an HTTP 401/403 error.

Interaction flow

For detailed descriptions of client events and server events, see Client events and Server events.

The API supports two modes:

• ServerCommit mode: The server determines text segmentation and synthesis timing automatically. You don't need to manage state manually.

• Commit mode : The client controls when to submit each text segment. Call input_text_buffer.commit explicitly to trigger synthesis.

Mode details

• In ServerCommit mode, call input_text_buffer.append multiple times. The system determines when to start synthesis based on internal rules.

• If input_text_buffer.commit is called in ServerCommit mode, the current buffer content is synthesized immediately. The session then continues in ServerCommit mode.

• In Commit mode, calling input_text_buffer.append alone doesn't trigger synthesis. Call input_text_buffer.commit explicitly to start synthesis.

Key steps:

1. Connection : The client initiates a WebSocket connection. The server returns a session.created event, indicating the session is ready.

2. Session configuration : The client sends a session.update event to set parameters such as voice, format, and mode.

3. Text input : The client sends input_text_buffer.append events to add text to the buffer.

4. Synthesis trigger:

   • In ServerCommit mode, the system determines synthesis timing automatically. The client can also call input_text_buffer.commit to force synthesis.

   • In Commit mode, only input_text_buffer.commit triggers synthesis.

5. Audio generation : The server sends response.created to indicate the task has started. It then streams audio chunks as response.audio.delta events (base64-encoded) until response.audio.done is received.

6. Session termination : The client sends session.finish to signal the server to release resources. The server returns session.finished and closes the connection.

After the connection is established, the server returns the following session.created event:

HELPCODEESCAPE-json
{
    "event_id": "event_xxx",
    "type": "session.created",
    "session": {
        "object": "realtime.session",
        "mode": "server_commit",
        "model": "qwen3-tts-flash-realtime",
        "voice": "Cherry",
        "response_format": "pcm",
        "sample_rate": 24000,
        "id": "sess_xxx"
    }
}