Skip to main content
SDK access

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.

Prerequisites

Before you begin, make sure that you have:

Complete example

The example code reads your_audio_file.pcm (PCM16, 16 kHz, mono). If you only have an MP3, WAV, or similar format, convert it with ffmpeg:
ffmpeg -i your_audio.mp3 -ar 16000 -ac 1 -f s16le your_audio_file.pcm
Python
import logging
import os
import signal
import sys
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor

# If you have not configured the API key in an environment variable, replace the following line with your own API key: api_key="sk-xxx"
client = dashscope.Client(api_key=os.environ.get('DASHSCOPE_API_KEY'))

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',
        # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
        # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
        ws_url='wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/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

client.audio.realtime.connect

The following parameters are set with client.audio.realtime.connect.
# If you have not configured the API key in an environment variable, replace the following line with your own API key: api_key="sk-xxx"
client = dashscope.Client(api_key=os.environ.get('DASHSCOPE_API_KEY'))

# Create a real-time recognition session: entering the with context automatically establishes the connection
session = client.audio.realtime.connect(
    model='qwen3-asr-flash-realtime',
    # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
    # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
    ws_url='wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime',
)
ParameterTypeRequiredDescription
modelstrYesModel to use.
ws_urlstrNoFull WebSocket endpoint. Pass wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime (Singapore). For another region, replace ap-southeast-1 in the URL. See Regions and endpoints.

Session configuration

After connecting, call update_session to configure session parameters.
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',
    },
)
ParameterTypeRequiredDescription
output_modalitiesList[str]YesOutput modality. Fixed to ["text"].
enable_turn_detectionboolNoEnables server-side Voice Activity Detection (VAD). Default: True. When False, call commit() manually to trigger recognition.
turn_detection_typestrNoServer-side VAD type. Fixed to server_vad.
turn_detection_thresholdfloatNoVAD sensitivity threshold. Default: 0.2. Recommended: 0.0. Valid range: [-1, 1].
Lower values = higher sensitivity (may trigger on background noise). Higher values = fewer false triggers in noisy environments.
turn_detection_silence_duration_msintNoSilence duration (ms) that marks the end of a statement. Default: 800. Recommended: 400. Valid range: [200, 6000].
Lower values (e.g., 300 ms) = faster response but may split natural pauses. Higher values (e.g., 1200 ms) = better handling of long-sentence pauses but higher latency.
transcription_paramsdictNoSpeech recognition configurations. See transcription_params.

transcription_params

Set speech recognition settings with the transcription_params dictionary of update_session.
session.update_session(
    output_modalities=['text'],
    enable_input_audio_transcription=True,
    transcription_params={
        'language': 'zh',
        'sample_rate': 16000,
        'input_audio_format': 'pcm',
    },
)
ParameterTypeRequiredDescription
languagestrNoSource language of the audio. Supported values:
zh (Chinese: Mandarin, Sichuanese, Minnan, Wu), yue (Cantonese), en (English), ja (Japanese), ko (Korean), de (German), fr (French), es (Spanish), pt (Portuguese), it (Italian), ru (Russian), ar (Arabic), hi (Hindi), id (Indonesian), th (Thai), tr (Turkish), uk (Ukrainian), vi (Vietnamese), cs (Czech), da (Danish), fi (Finnish), fil (Filipino), is (Icelandic), ms (Malay), no (Norwegian), pl (Polish), sv (Swedish)
sample_rateintNoAudio sampling rate in Hz. Default: 16000. Supported: 16000, 8000. With 8000, the server upsamples to 16,000 Hz before recognition, which may add minor latency. Use 8000 only for 8 kHz source audio like telephone recordings.
input_audio_formatstrNoAudio format. Default: pcm. Supported: pcm, opus.
corpus_textstrNoBackground text, entity vocabularies, or other reference information for contextual biasing. Max: 10,000 tokens. For details, see Contextual biasing.

Key interfaces

RealtimeSession class

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).
MethodServer response event (delivered via events())Description
connect()session.created, session.updatedOpens a WebSocket connection to the server. Automatically called when entering the with context; do not call connect() and then enter the with context of the same session.
update_session(...)session.updatedConfigures the session. Call after connect(). If omitted, defaults apply. See Session configuration for parameters.
append_audio(audio: Union[str, bytes])NoneAppends an audio chunk to the server input buffer. A str is treated as already Base64-encoded; bytes are automatically Base64-encoded. With enable_turn_detection=True, the server detects speech boundaries and commits automatically. With enable_turn_detection=False, the client controls commit timing (max 15 MiB per event). Smaller chunks improve VAD responsiveness.
commit()input_audio_buffer.committedCommits buffered audio for recognition. Returns an error if the buffer is empty. Disabled when enable_turn_detection=True.
end_session()session.finishedEnds the session after the server completes final recognition. In VAD mode (default), call after sending all audio. In Manual mode, call after commit().
close()NoneTerminates the task and closes the connection (idempotent, does not send session.finish).
events()Server events (the event type is in event["type"])Continuously reads server events. The iteration ends after session.finished is yielded; consume events from a single receiver thread and do not create multiple concurrent readers.
session.session_id, session.last_response_idNoneThe 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 the full event list in Server events).
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']}")
MethodParametersDescription
events()event: a server eventContinuously reads and yields server events (dict). The iteration ends when the connection closes or session.finished is received.
recv_event()NoneBlocks to read a single server event without looping; returns None when there are no events (the connection is closed).