Qwen-ASR-Realtime receives audio streams and transcribes speech in real time over WebSocket. The service supports two interaction modes: VAD mode and Manual mode .
User guide: For model overviews and selection guidance, see Speech-to-text. For sample code, see Real-time speech recognition.
Rate limits: Model calls are subject to rate limits. When a limit is exceeded, the server returns the error
Specify the model with the
Include the following fields in the request headers:
For details about client and server events, see Client events for Qwen-ASR-Realtime and Server events.
Qwen-ASR-Realtime supports two interaction modes:
The server default for
The client controls utterance boundaries. After sending the audio for a complete utterance, the client sends a input_audio_buffer.commit event to notify the server. Use this mode when the client can determine those boundaries explicitly, such as sending a voice message in a messaging app.
To enable: Set
These examples use qwen3-asr-flash-realtime. Get your API key and Base URL from the console, and set them as
Requests rate limit exceeded, please try again later. Reduce your request rate or concurrency and retry. For the rate limits of each model, see Rate limiting.
Service endpoint
Specify the model with the model query parameter:
wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime?model=<model_name>
This example uses Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL, for example cn-beijing for China North 2 (Beijing), and use an API key from that region. See Regions.
Use
wss:// and pass Authorization: Bearer $DASHSCOPE_API_KEY in the WebSocket handshake.Request headers
Include the following fields in the request headers:
| Parameter | Type | Required | Description |
|---|---|---|---|
| Authorization | string | Yes | Authentication token in the format Bearer $DASHSCOPE_API_KEY. Replace $DASHSCOPE_API_KEY with your API key. |
| user-agent | string | No | Client identifier that helps the server track request sources. |
| X-DashScope-WorkSpace | string | No | The QwenCloud workspace ID. |
| X-DashScope-DataInspection | string | No | Whether to enable data inspection. Omit this header unless data inspection is required; if it is, set the value to enable. |
Authorization is verified during the WebSocket handshake. If the API key is invalid or missing, the handshake fails with an HTTP 401 or 403 error.
Interaction flows
For details about client and server events, see Client events for Qwen-ASR-Realtime and Server events.
Qwen-ASR-Realtime supports two interaction modes:
- VAD mode (default): The server uses voice activity detection (VAD) to automatically detect the start and end of each utterance. Use this mode for real-time conversations, meeting transcription, and similar scenarios.
- Manual mode: The client controls utterance boundaries. Use this mode when the client can determine those boundaries explicitly, such as sending a voice message in a messaging app.
VAD mode (default)
The server default for silence_duration_ms is 800; 400 is a reference setting for conversations that need faster segmentation. The server default for threshold is 0.2. For the full configuration, see Client events.
The server automatically detects the start and end of each utterance. Send the audio stream continuously; the server returns the final transcription for each utterance once it detects the end. Use this mode for real-time conversations, meeting transcription, and similar scenarios.
To enable: Configure the session.turn_detection parameter in the client session.update event.
- The client sends input_audio_buffer.append events to append audio to the buffer.
- The server returns a input_audio_buffer.speech_started event when speech is detected. Note: If the client sends session.finish to end the session before this event arrives, the server immediately returns a session.finished event. The client must then close the connection.
- The client continues to send input_audio_buffer.append events to submit audio.
- After sending all audio, the client sends a session.finish event to end the session.
In VAD mode, the client must send a
session.finish event before closing the connection. If the client closes the WebSocket connection without first sending session.finish, the server discards the current in-progress item and events such as conversation.item.input_audio_transcription.completed will not be delivered. Send {"type":"session.finish"} before calling ws.Close(), and wait for the session.finished event before closing the connection.- The server returns a input_audio_buffer.speech_stopped event when it detects the end of speech.
- The server returns a input_audio_buffer.committed event.
- The server returns a conversation.item.created event.
- The server returns a conversation.item.input_audio_transcription.text event that contains partial transcription results.
- The server returns a conversation.item.input_audio_transcription.completed event that contains the final transcription result.
- The server returns a session.finished event to signal that recognition is complete. The client must then close the connection.
Manual mode
The client controls utterance boundaries. After sending the audio for a complete utterance, the client sends a input_audio_buffer.commit event to notify the server. Use this mode when the client can determine those boundaries explicitly, such as sending a voice message in a messaging app.
To enable: Set session.turn_detection to null in the client session.update event.
- The client sends input_audio_buffer.append events to append audio to the buffer.
- The client sends a input_audio_buffer.commit event to commit the input audio buffer. The commit creates a new user message item in the conversation.
- The client sends a session.finish event to end the session.
- The server returns a input_audio_buffer.committed event.
- The server returns a conversation.item.input_audio_transcription.text event that contains partial transcription results.
- The server returns a conversation.item.input_audio_transcription.completed event that contains the final transcription result.
- The server returns a session.finished event to signal that recognition is complete. The client must then close the connection.
Examples
These examples use qwen3-asr-flash-realtime. Get your API key and Base URL from the console, and set them as DASHSCOPE_API_KEY and DASHSCOPE_BASE_URL.
Download the sample audio as asr_example.wav: a 16 kHz, mono WAV file with 16-bit PCM encoding.
The example code reads
asr_example.pcm (PCM16, 16 kHz, mono). If you only have an MP3, WAV, or similar format, convert it with ffmpeg:- Java
- Python
- Go
- Node.js
- C#
- PHP
Before you run the example, install the Java-WebSocket dependency:
Maven