Client events - Alibaba Cloud Model Studio

For the full API overview, see Real-time speech synthesis - Qwen.

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.

session properties

`voice`

Type: string | Required: YesThe voice for speech synthesis. For voice samples, see Supported 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.

`mode`

Type: string | Required: No | Default: server_commitThe 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.

`language_type`

Type: string | Required: No | Default: AutoThe 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`

`response_format`

Type: string | Required: No | Default: pcmThe audio output format.

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

`sample_rate`

Type: integer | Required: No | Default: 24000The sample rate of the audio output, in Hz.Supported values: 8000, 16000, 24000, 48000.

Note: The Qwen-TTS-Realtime series supports only 24000. See Supported models.

`speech_rate`

Type: float | Required: No | Default: 1.0 | Range: 0.5--2.0The playback speed. Values below 1.0 slow down the audio; values above 1.0 speed it up.

Note: Not supported by the Qwen-TTS-Realtime series. See Supported models.

`volume`

Type: integer | Required: No | Default: 50 | Range: 0--100The audio volume.

Note: Not supported by the Qwen-TTS-Realtime series. See Supported models.

`pitch_rate`

Type: float | Required: No | Default: 1.0 | Range: 0.5--2.0The pitch of the synthesized audio.

Note: Not supported by the Qwen-TTS-Realtime series. See Supported models.

`bit_rate`

Type: integer | Required: No | Default: 128 | Range: 6--510Audio bitrate in kbps. Higher values produce better quality but larger files. Only applies when response_format is opus.

Note: Not supported by the Qwen-TTS-Realtime series. See Supported models.

`instructions`

Type: string | Required: No | Default: None | Max length: 1600 tokensControls style and expressiveness of synthesized speech. For details, see Real-time speech synthesis - Qwen.Supported languages: Chinese and English only.

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

`optimize_instructions`

Type: boolean | Required: No | Default: falseWhen true, rewrites instructions to improve naturalness and expressiveness. Enable for use cases requiring fine-grained vocal control.Has no effect if instructions is empty.

Note: 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.

Note: 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`.

​Event summary

​session.update

​Request body

​Parameters

voice

mode

language_type

response_format

sample_rate

speech_rate

volume

pitch_rate

bit_rate

instructions

optimize_instructions

​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

Event summary

`session.update`

Request body

Parameters

`voice`

`mode`

`language_type`

`response_format`

`sample_rate`

`speech_rate`

`volume`

`pitch_rate`

`bit_rate`

`instructions`

`optimize_instructions`

`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