time speech synthesis API reference (Qwen-TTS-Realtime)-Client events

Client events are JSON messages sent over a WebSocket connection to control the Qwen-TTS Realtime API session -- configure voice settings, stream text for synthesis, and signal completion.

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

HELPCODEESCAPE-json
{
    "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: Yes

The 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_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.

language_type

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

response_format

Type: string | Required: No | Default: pcm

The 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: 24000

The 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.0

The 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--100

The 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.0

The 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--510

Audio 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 tokens

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

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

HELPCODEESCAPE-json
{
    "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

HELPCODEESCAPE-json
{
    "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

HELPCODEESCAPE-json
{
    "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

HELPCODEESCAPE-json
{
    "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.