Qwen-ASR-Realtime Python SDK - API reference
Stream audio to Qwen-ASR-Realtime over WebSocket and receive real-time transcription results via the DashScope Python SDK.
ImportantAlibaba Cloud Model Studio has launched workspace-specific domains for the China (Beijing) and Singapore regions, which deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:
- China (Beijing) region: from
dashscope.aliyuncs.comto{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore region: from
dashscope-intl.aliyuncs.comto{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Replace {WorkspaceId} with your actual Workspace ID. The existing domains remain fully functional.
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
NoteThe example code reads your_audio_file.pcm (PCM16, 16 kHz, mono). If you only have formats such as MP3 or WAV, convert them with ffmpeg:
ffmpeg -i your_audio.mp3 -ar 16000 -ac 1 -f s16le your_audio_file.pcm
import logging
import os
import signal
import sys
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor
# The API Key differs between the Singapore and Beijing regions. Get your API Key: https://help.aliyun.com/zh/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key="sk-xxx"
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
# The following is the configuration for the China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ by region.
workspace="{WorkspaceId}",
region="cn-beijing",
)
def setup_logging():
"""Configure log output"""
logger = logging.getLogger('dashscope')
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(sys.stdout)
handler.setLevel(logging.DEBUG)
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)
logger.propagate = False
return logger
def handle_event(event):
"""Handle a server-side event"""
kind = event.get('type')
if kind == 'session.created':
print(f"Start session: {event['session']['id']}")
elif kind == 'conversation.item.input_audio_transcription.completed':
print(f"Final recognized text: {event['transcript']}")
elif kind == 'conversation.item.input_audio_transcription.text':
print(f"Got transcription result: {event['text'] + event['stash']}")
elif kind == 'input_audio_buffer.speech_started':
print('======Speech Start======')
elif kind == 'input_audio_buffer.speech_stopped':
print('======Speech Stop======')
def receive_events(session):
"""Receive and process server-side events"""
for event in session.events():
handle_event(event)
def read_audio_chunks(file_path, chunk_size=3200):
"""Read the audio file in chunks"""
with open(file_path, 'rb') as f:
while chunk := f.read(chunk_size):
yield chunk
def send_audio(session, file_path, delay=0.1):
"""Send audio data"""
if not os.path.exists(file_path):
raise FileNotFoundError(f"Audio file {file_path} does not exist.")
print("Processing audio file... Press 'Ctrl+C' to stop.")
for chunk in read_audio_chunks(file_path):
session.append_audio(chunk) # bytes are automatically Base64-encoded before being sent
time.sleep(delay)
def main():
setup_logging()
audio_file_path = "./your_audio_file.pcm"
# Entering the with context automatically establishes the connection
with client.audio.realtime.connect(
model='qwen3-asr-flash-realtime',
) as session:
def handle_exit(sig, frame):
print('Ctrl+C pressed, exiting...')
session.close()
sys.exit(0)
signal.signal(signal.SIGINT, handle_exit)
# Update the session configuration: text output only, with input audio transcription enabled
session.update_session(
output_modalities=['text'],
enable_input_audio_transcription=True,
transcription_params={
'language': 'zh',
'sample_rate': 16000,
'input_audio_format': 'pcm',
},
)
# Read until session.updated to confirm that the configuration has taken effect
for event in session.events():
if event.get('type') == 'session.updated':
break
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_events, session)
try:
send_audio(session, audio_file_path)
# send session.finish and wait for finished and close
session.end_session()
receiver.result()
finally:
# close must run inside the pool context to unblock the receiver
session.close()
print("Audio processing completed.")
if __name__ == '__main__':
main()
Request parameters
-
The following parameters are set with the
client.audio.realtime.connectmethod.Click to view sample code
# The API Key differs between the Singapore and Beijing regions. Get your API Key: https://help.aliyun.com/zh/model-studio/get-api-key # If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: api_key="sk-xxx" client = dashscope.Client( api_key=os.environ.get('DASHSCOPE_API_KEY'), # The following is the configuration for the China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. Configurations differ by region. workspace="{WorkspaceId}", region="cn-beijing", ) # Create a real-time recognition session: entering the with context automatically establishes the connection session = client.audio.realtime.connect( model='qwen3-asr-flash-realtime', )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
session.update_session( output_modalities=['text'], enable_turn_detection=True, turn_detection_type="server_vad", turn_detection_threshold=0.0, turn_detection_silence_duration_ms=400, enable_input_audio_transcription=True, transcription_params={ 'language': 'zh', 'sample_rate': 16000, 'input_audio_format': 'pcm', }, )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
session.update_session( output_modalities=['text'], enable_input_audio_transcription=True, transcription_params={ 'language': 'zh', 'sample_rate': 16000, 'input_audio_format': 'pcm', }, )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 |
|---|---|---|
|
| Establishes a connection with the server. Automatically called when entering the |
|
| 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
|
|
| 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 |
|
| 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 |
|
| Continuously reads server events. After |
| 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).
def receive_events(session):
for event in session.events():
kind = event.get('type')
if kind == 'session.created':
print(f"Start session: {event['session']['id']}")
elif kind == 'conversation.item.input_audio_transcription.completed':
print(f"Final recognized text: {event['transcript']}")
elif kind == 'conversation.item.input_audio_transcription.text':
print(f"Got transcription result: {event['text'] + event['stash']}")
| Method signature | Parameters | Description |
|---|---|---|
| event: server event | Continuously reads and yields server events ( |
| None | Blocks to read a single server event without looping; returns |