Skip to main content

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.

Alibaba 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.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore region: from dashscope-intl.aliyuncs.com to {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Replace {WorkspaceId} with your actual Workspace ID. The existing domains remain fully functional.

Prerequisites

  1. Install the SDK, and make sure the DashScope SDK version is 2.0.1 or later.
  2. Get and configure an API key.
  3. Learn about the WebSocket API.

Quick start

The 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
Python
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.connect method.
    # 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

    model

    str

    Yes

    Name of the model to use.

    ws_url

    str

    No

    Full WebSocket endpoint. If not specified, the endpoint is automatically selected based on the workspace and region of the Client:

    • 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_session method of RealtimeSession.
    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_modalities

    List[str]

    Yes

    Model output modality, fixed to ["text"].

    enable_turn_detection

    bool

    No

    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: enabled

    • False: disabled

    turn_detection_type

    str

    No

    Server-side VAD type, fixed to server_vad.

    turn_detection_threshold

    float

    No

    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_ms

    int

    No

    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_params

    dict

    No

    Speech recognition related configurations.

  • The following parameters are set 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',
        },
    )
    

    Parameter

    Type

    Required

    Description

    language

    str

    No

    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_rate

    int

    No

    Audio sampling rate (Hz). Supports 16000 and 8000.

    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_format

    str

    No

    Audio format. Supports pcm and opus.

    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 signatureServer response events (delivered via events())Description
def connect(self) -> RealtimeSession
session.created
Session created
session.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.
def update_session(self,
                   output_modalities: List[str] = ...,
                   *,
                   voice: str = ...,
                   input_audio_format: str = ...,
                   output_audio_format: str = ...,
                   enable_input_audio_transcription: bool = ...,
                   input_audio_transcription_model: str = ...,
                   enable_turn_detection: bool = ...,
                   turn_detection_type: str = ...,
                   prefix_padding_ms: int = ...,
                   turn_detection_threshold: float = ...,
                   turn_detection_silence_duration_ms: int = ...,
                   turn_detection_param: dict = ...,
                   translation_params: dict = ...,
                   transcription_params: dict = ...,
                   ...) -> None
session.updated
Session 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.
def append_audio(self, audio_b64: Union[str, bytes]) -> None
NoneAppends an audio chunk to the cloud input audio buffer. A str is treated as already Base64-encoded; bytes are automatically Base64-encoded.
  • With Request parameters enable_turn_detection set to True, the audio buffer is used to detect speech and the server decides when to commit.
  • With Request parameters enable_turn_detection set to False, the client can choose how much audio to place in each event, up to 15 MiB. For example, streaming smaller chunks from the client allows the VAD to respond more quickly.
def commit(self) -> None
input_audio_buffer.committed
The 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.
def end_session(self) -> None
session.finished
The 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:
def close(self) -> None
NoneTerminates the task and closes the connection (idempotent, does not send session.finish).
def events(self) -> Iterator[Dict]
Server events
Event types are in event["type"]
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.
session.session_id
session.last_response_id
NoneGets 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 signatureParametersDescription
def events(self) -> Iterator[Dict]
event: server eventContinuously reads and yields server events (dict) one by one. The iteration ends when the connection is closed or session.finished is received.
def recv_event(self) -> Optional[Dict]
NoneBlocks to read a single server event without looping; returns None when there are no events (the connection is closed).