Qwen-TTS client events

For the full API overview, see Realtime streaming TTS.

Endpoint

Connect to the WebSocket endpoint:

wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime?model={model}

Replace {model} with your model ID, such as qwen3-tts-instruct-flash-realtime.

Event summary

Client event	Server response	Description
`session.update`	`session.updated`	Set voice, audio format, interaction mode, and other session parameters
`input_text_buffer.append`	--	Append text to the synthesis buffer
`input_text_buffer.commit`	`input_text_buffer.committed`	Commit buffered text to trigger synthesis
`input_text_buffer.clear`	`input_text_buffer.cleared`	Discard all buffered text
`session.finish`	--	End the session; the server flushes remaining audio and closes the connection

session.update

Configures the session. Send as the first message after the WebSocket connection is established. If omitted, all parameters use defaults. The server confirms with a session.updated event.

Request body

{
    "event_id": "event_123",
    "type": "session.update",
    "session": {
        "voice": "Cherry",
        "mode": "server_commit",
        "language_type": "Chinese",
        "response_format": "pcm",
        "sample_rate": 24000,
        "instructions": "",
        "optimize_instructions": false
    }
}

Parameters

Parameter	Type	Required	Description
`event_id`	string	Yes	Unique event identifier generated by the client (UUID recommended). Must be unique within the WebSocket session.
`type`	string	Yes	Set to `session.update`.
`session`	object	No	Session configuration. See the following subsections.

Show session properties

string

body

required

The voice for speech synthesis. For voice samples, see System voices.

System voices: Available only for the Qwen3-TTS-Instruct-Flash-Realtime, Qwen3-TTS-Flash-Realtime, and Qwen-TTS-Realtime model series.
Custom voices:
- Voices created through Voice cloning (Qwen): Available for the Qwen3-TTS-VC-Realtime series only.
- Voices created through Voice design (Qwen): Available for the Qwen3-TTS-VD-Realtime series only.

string

body

default"server_commit"

The interaction mode that controls when buffered text is synthesized.

Value	Behavior
`server_commit`	The server decides when to synthesize, balancing latency and quality. Recommended for most uses.
`commit`	Trigger synthesis manually by sending `input_text_buffer.commit`. Lowest latency, but you must manage sentence integrity.

string

body

default"Auto"

The language of the synthesized audio.

Auto -- For unknown or mixed-language text. The model automatically matches pronunciation per segment, but accuracy is not guaranteed.
For single-language text, specifying language significantly improves quality. Supported values:

Value	Value	Value
`Chinese`	`English`	`German`
`Italian`	`Portuguese`	`Spanish`
`Japanese`	`Korean`	`French`
`Russian`

string

body

default"pcm"

The audio output format.

Value	Notes
`pcm`	Default. Only format supported by Qwen-TTS-Realtime series.
`wav`
`mp3`
`opus`	Supports configurable bitrate via the `bit_rate` parameter.

integer

body

default"24000"

The sample rate of the audio output, in Hz.Supported values: 8000, 16000, 24000, 48000.

The Qwen-TTS-Realtime series supports only 24000.

float

body

default"1.0"

The playback speed. Values below 1.0 slow down the audio; values above 1.0 speed it up. Range: 0.5--2.0.

Not supported by the Qwen-TTS-Realtime series.

integer

body

default"50"

The audio volume. Range: 0--100.

Not supported by the Qwen-TTS-Realtime series.

float

body

default"1.0"

The pitch of the synthesized audio. Range: 0.5--2.0.

Not supported by the Qwen-TTS-Realtime series.

integer

body

default"128"

Audio bitrate in kbps. Higher values produce better quality but larger files. Only applies when response_format is opus. Range: 6--510.

Not supported by the Qwen-TTS-Realtime series.

string

body

Controls style and expressiveness of synthesized speech. For details, see Realtime streaming TTS. Max length: 1600 tokens.Supported languages: Chinese and English only.

Available for the Qwen3-TTS-Instruct-Flash-Realtime series only.

boolean

body

default"false"

When true, rewrites instructions to improve naturalness and expressiveness. Enable for use cases requiring fine-grained vocal control.Has no effect if instructions is empty.

Available for the Qwen3-TTS-Instruct-Flash-Realtime series only.

input_text_buffer.append

Append text to the synthesis buffer.

In server_commit mode, text is appended to the server-side buffer.
In commit mode, text is appended to the client-side buffer.

Request body

{
    "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
    "type": "input_text_buffer.append",
    "text": "Hello, I am Qwen."
}

Parameters

Parameter	Type	Required	Description
`event_id`	string	Yes	Unique event identifier generated by the client (UUID recommended). Must be unique within the WebSocket session.
`type`	string	Yes	Set to `input_text_buffer.append`.
`text`	string	Yes	The text to synthesize.

input_text_buffer.commit

Commits buffered text and creates a user message item. The server responds with an input_text_buffer.committed event. Returns an error if the buffer is empty. Behavior differs by mode:

server_commit mode: All buffered text is synthesized immediately. The server stops caching and processes everything at once.
commit mode: Creates user message item from buffered text.

Committing the buffer triggers synthesis only -- it does not generate a model response.

Request body

{
  "event_id": "event_B4o9RHSTWobB5OQdEHLTo",
  "type": "input_text_buffer.commit"
}

Parameters

Parameter	Type	Required	Description
`event_id`	string	Yes	Unique event identifier generated by the client (UUID recommended). Must be unique within the WebSocket session.
`type`	string	Yes	Set to `input_text_buffer.commit`.

input_text_buffer.clear

Clears buffer text. The server responds with an input_text_buffer.cleared event.

Request body

{
  "event_id": "event_2728",
  "type": "input_text_buffer.clear"
}

Parameters

Parameter	Type	Required	Description
`event_id`	string	Yes	Unique event identifier generated by the client (UUID recommended). Must be unique within the WebSocket session.
`type`	string	Yes	Set to `input_text_buffer.clear`.

session.finish

Signals no more text will be sent. The server returns remaining audio and closes the connection.

Request body

{
  "event_id": "event_2239",
  "type": "session.finish"
}

Parameters

Parameter	Type	Required	Description
`event_id`	string	Yes	Unique event identifier generated by the client (UUID recommended). Must be unique within the WebSocket session.
`type`	string	Yes	Set to `session.finish`.

​Endpoint

​Event summary

​session.update

​Request body

​Parameters

​input_text_buffer.append

​Request body

​Parameters

​input_text_buffer.commit

​Request body

​Parameters

​input_text_buffer.clear

​Request body

​Parameters

​session.finish

​Request body

​Parameters

Endpoint

Event summary

session.update

Request body

Parameters

input_text_buffer.append

Request body

Parameters

input_text_buffer.commit

Request body

Parameters

input_text_buffer.clear

Request body

Parameters

session.finish

Request body

Parameters