Skip to main content

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 eventServer responseDescription
session.updatesession.updatedSet voice, audio format, interaction mode, and other session parameters
input_text_buffer.append--Append text to the synthesis buffer
input_text_buffer.commitinput_text_buffer.committedCommit buffered text to trigger synthesis
input_text_buffer.clearinput_text_buffer.clearedDiscard 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
    }
}

Parameters

ParameterTypeRequiredDescription
event_idstringYesUnique event identifier generated by the client (UUID recommended). Must be unique within the WebSocket session.
typestringYesSet to session.update.
sessionobjectNoSession configuration. See the following subsections.

session properties

voice

Type: string | Required: YesThe system voice used for speech synthesis. See Supported voices.

mode

Type: string | Required: No | Default: server_commitThe interaction mode that controls when buffered text is synthesized.
ValueBehavior
server_commitThe server decides when to synthesize, balancing latency and quality. Recommended for most uses.
commitTrigger 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:
ValueValueValue
ChineseEnglishGerman
ItalianPortugueseSpanish
JapaneseKoreanFrench
Russian

response_format

Type: string | Required: No | Default: pcmThe audio output format.
ValueNotes
pcmDefault.
wav
mp3
opusSupports 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.

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.

volume

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

pitch_rate

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

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.

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

ParameterTypeRequiredDescription
event_idstringYesUnique event identifier generated by the client (UUID recommended). Must be unique within the WebSocket session.
typestringYesSet to input_text_buffer.append.
textstringYesThe 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

ParameterTypeRequiredDescription
event_idstringYesUnique event identifier generated by the client (UUID recommended). Must be unique within the WebSocket session.
typestringYesSet 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

ParameterTypeRequiredDescription
event_idstringYesUnique event identifier generated by the client (UUID recommended). Must be unique within the WebSocket session.
typestringYesSet 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

ParameterTypeRequiredDescription
event_idstringYesUnique event identifier generated by the client (UUID recommended). Must be unique within the WebSocket session.
typestringYesSet to session.finish.
API Usage
Text Generation
Image Generation
Video Generation
World models
Audio
Real-time Multimodal
Realtime API
Text Embedding
Decision Model
More Models
Toolkit/Framework
TokenPlan
Model Production
File Management
Billing
Model Management
More