Stream audio to Qwen-ASR-Realtime over WebSocket and receive real-time transcription results via the DashScope Python SDK.
Prerequisites
- Install the SDK, and make sure the DashScope SDK version is 2.0.1 or later.
- Get and configure an API key.
- Learn about the WebSocket API.
Quick start
your_audio_file.pcm (PCM16, 16 kHz, mono). If you only have formats such as MP3 or WAV, convert them with ffmpeg:Request parameters
-
The following parameters are set with the
client.audio.realtime.connectmethod.Click to view sample code
Parameter
Type
Required
Description
modelstrYes
Name of the model to use.
ws_urlstrNo
Full WebSocket endpoint. If not specified, the endpoint is automatically selected based on the
workspaceandregionof theClient:China (Beijing) region:
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime. Replace{WorkspaceId}with your actual Workspace ID when calling.Singapore region:
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime. Replace{WorkspaceId}with your actual workspace ID when calling.
-
The following parameters are set with the
update_sessionmethod ofRealtimeSession.Click to view sample code
Parameter
Type
Required
Description
output_modalitiesList[str]Yes
Model output modality, fixed to
["text"].enable_turn_detectionboolNo
Whether to enable server-side Voice Activity Detection (VAD). When disabled, you must manually call the
commit()method to trigger recognition.Default:
True.Valid values:
True: enabledFalse: disabled
turn_detection_typestrNo
Server-side VAD type, fixed to
server_vad.turn_detection_thresholdfloatNo
VAD detection threshold. We recommend setting this value to
0.0.Default:
0.5.Valid range:
[-1, 1].A lower threshold increases VAD sensitivity and may misclassify background noise as speech. A higher threshold reduces sensitivity and helps reduce false triggers in noisy environments.
turn_detection_silence_duration_msintNo
VAD silence detection threshold (ms). Silence lasting longer than this threshold is treated as the end of an utterance. We recommend setting this value to
400.Default:
800.Valid range:
[200, 6000].A lower value (e.g., 300 ms) allows the model to respond faster but may cause unreasonable segmentation at natural pauses. A higher value (e.g., 1200 ms) better handles pauses within long sentences but increases overall response latency.
transcription_paramsdictNo
Speech recognition related configurations.
-
The following parameters are set with the
transcription_paramsdictionary ofupdate_session.Click to view sample code
Parameter
Type
Required
Description
languagestrNo
Source language of the audio.
zh: Chinese (Mandarin, Sichuanese, Minnan, Wu)
yue: Cantonese
en: English
ja: Japanese
de: German
ko: Korean
ru: Russian
fr: French
pt: Portuguese
ar: Arabic
it: Italian
es: Spanish
hi: Hindi
id: Indonesian
th: Thai
tr: Turkish
uk: Ukrainian
vi: Vietnamese
cs: Czech
da: Danish
fil: Filipino
fi: Finnish
is: Icelandic
ms: Malay
no: Norwegian
pl: Polish
sv: Swedish
sample_rateintNo
Audio sampling rate (Hz). Supports
16000and8000.Default:
16000.When set to
8000, the server first upsamples the audio to 16,000 Hz before recognition, which may introduce minor latency. We recommend using it only when the source audio is 8,000 Hz (such as telephone lines).input_audio_formatstrNo
Audio format. Supports
pcmandopus.Default:
pcm.
API reference
RealtimeSession (client.audio.realtime.connect)
A real-time recognition session is created with client.audio.realtime.connect(model=...): the connection is established when you enter the with context (or call the session's connect() method).
| Method signature | Server response events (delivered via events()) | Description |
|---|---|---|
session.createdSession createdsession.updated Session configuration updated | Establishes a connection with the server. Automatically called when entering the with context; do not call connect() first and then enter the with context of the same session. | |
session.updatedSession configuration updated | Used to update the session configuration. We recommend calling this method first after the connection is established. If this method is not called, the system uses the default configuration. Only the parameters listed in Request parameters are relevant. | |
| None | Appends an audio chunk to the cloud input audio buffer. A str is treated as already Base64-encoded; bytes are automatically Base64-encoded.
| |
input_audio_buffer.committedThe server received the committed audio | Commits the audio and video previously added to the cloud buffer via append_audio. An error occurs if the input audio buffer is empty.Disabled when: Request parameters enable_turn_detection is set to True. | |
session.finishedThe server completed speech recognition and ended the session | Notifies the server to end the session. After receiving the end-of-session notification, the server completes the final speech recognition.When to call:
| |
| None | Terminates the task and closes the connection (idempotent, does not send session.finish). | |
Server events
Event types are in | Continuously reads server events. After session.finished is received, the event is yielded and the iteration ends; keep a single receiver thread consuming events and do not create multiple concurrent readers. | |
| None | Gets the session_id of the current task and the response_id of the most recent response (attributes). |
Event iteration (events())
The server returns response events and data to the client as events. Iterate the session's events() in a receiver thread and dispatch on event["type"] (see Server events for the full event list).
| Method signature | Parameters | Description |
|---|---|---|
| event: server event | Continuously reads and yields server events (dict) one by one. The iteration ends when the connection is closed or session.finished is received. | |
| None | Blocks to read a single server event without looping; returns None when there are no events (the connection is closed). |