Live speech to text
The real-time speech recognition service receives an audio stream and transcribes it into punctuated text in real time. Use it for live captioning, online meetings, voice chat, smart assistants, and similar scenarios.
Overview
The service streams audio and returns transcribed text with low latency.
In addition to WebSocket, Qwen-Audio-3.0-ASR-Flash-Streaming and Fun-ASR-Realtime models also support the AOQ protocol. For client-side integration that prioritizes stable latency, resilience on weak networks, and built-in full-duplex noise suppression and echo cancellation, AOQ is recommended. For a protocol comparison, see Realtime API overview.
By providing context, you can optimize the recognition of domain-specific vocabulary, such as names, places, and product terms.
Length limit: The context content cannot exceed 10,000 tokens.
Usage:
To achieve the result above, add any of the following content to the context:
Sensitive word filtering replaces or removes sensitive words in the recognition result. Use it for call-center quality inspection, content compliance, subtitle review, and similar scenarios.
Supported models: Qwen-Audio-3.0-ASR-Flash-Streaming and Fun-ASR-Realtime only.
Limit: You can set up to 32 sensitive words.
Default behavior: When the
Different SDKs expose these parameters with their own naming conventions (dictionary keys, object properties, methods, and so on). For the complete field mapping, see the API reference.
Qwen real-time speech recognition streams audio over WebSocket. Two modes are available: VAD mode (default) and Manual mode.
Replace
The server detects speech boundaries and segments sentences. The client streams audio, and the server returns results when each sentence ends. Best for conversations and meeting transcription.
Enable: Set
The client controls sentence segmentation by sending audio for a complete sentence, then sending
You can also use Qwen-Omni (
ASR prompt template:
- Recognizes Mandarin Chinese with high accuracy, plus Cantonese, Sichuanese, and other dialects.
- Handles complex acoustic environments, with automatic language detection and intelligent filtering of non-speech audio.
- Recognizes a range of emotional states, including surprise, calm, happiness, sadness, disgust, anger, and fear.
- Supports custom hotwords to improve recognition accuracy for specific terms.
- Supports context enhancement to improve recognition accuracy by passing in conversation history or domain terms.
- Outputs timestamps to produce structured recognition results.
- Accepts flexible sample rates and multiple audio formats to fit different recording environments.
For model availability, supported languages, and feature comparison, see Speech-to-text models.
Getting started
- Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime
- Qwen3-ASR-Flash-Realtime
- DashScope SDK
- WebSocket API
For more code samples, see GitHub.Get an API key and set it as an environment variable. To use the SDK, install it.
Model availability
| Model | Version | Unit price | Free quota (Note) |
|---|---|---|---|
| fun-asr-realtime Currently, fun-asr-realtime-2025-11-07 | Stable | $0.00009/second | 36,000 seconds (10 hours) Valid for 90 days |
| fun-asr-realtime-2025-11-07 | Snapshot | $0.00009/second | 36,000 seconds (10 hours) Valid for 90 days |
- Languages: Mandarin, Cantonese, Wu, Minnan, Hakka, Gan, Xiang, and Jin. Also supports Mandarin accents from Zhongyuan, Southwest, Jilu, Jianghuai, Lanyin, Jiaoliao, Northeast, Beijing, and Hong Kong-Taiwan regions -- including Henan, Shaanxi, Hubei, Sichuan, Chongqing, Yunnan, Guizhou, Guangdong, Guangxi, Hebei, Tianjin, Shandong, Anhui, Nanjing, Jiangsu, Hangzhou, Gansu, and Ningxia. English and Japanese are also supported.
- Sample rate: 16 kHz
- Audio formats: pcm, wav, mp3, opus, speex, aac, amr
Recognize speech from a microphone
Recognize speech from a microphone and output text in real time, so words appear as the speaker talks.Before you run the Python example, install the third-party audio playback and capture toolkit with
pip install pyaudio. pyaudio requires the portaudio library. On Ubuntu/Debian: sudo apt-get install libportaudio2 portaudio19-dev. On macOS: brew install portaudio.Recognize a local audio file
Recognize a local audio file and output the result. This suits shorter, near-real-time scenarios such as chat conversations, voice commands, voice input methods, and voice search.Going live
Improve recognition accuracy
- Choose a model that matches the sample rate: For 8 kHz telephone audio, use an 8 kHz model directly. This avoids the information loss caused by upsampling to 16 kHz.
- Use hotwords or context enhancement: For proprietary nouns, names, and brand names specific to your business, you can configure hotwords or context enhancement to significantly improve recognition accuracy. For detailed configuration methods and usage notes, see Improve recognition accuracy.
- Improve the input audio quality: Use a high-quality microphone and record in an environment with a high signal-to-noise ratio and no echo. At the application layer, you can integrate algorithms such as noise reduction (for example, RNNoise) and acoustic echo cancellation (AEC) for preprocessing.
- Specify the recognition language: For multilingual models, if you can predetermine the audio language when making a call, it helps the model converge and avoid confusion between similarly pronounced languages, which improves accuracy.
Set up a fault-tolerance strategy
- Client-side reconnection: The client should implement automatic reconnection to handle network jitter. The following is a reference implementation for the Python SDK:
- Catch exceptions: Implement the
on_errormethod in theCallbackclass. ThedashscopeSDK calls this method when it encounters a network error or another issue. - Signal the state: When
on_erroris triggered, set a reconnection signal. In Python, you can usethreading.Event, a thread-safe signal flag. - Reconnection loop: Wrap the main logic in a
forloop (for example, retry 3 times). When the reconnection signal is detected, the current recognition round is interrupted, resources are cleaned up, and after a few seconds the loop runs again to create a brand-new connection.
- Catch exceptions: Implement the
- Set a heartbeat to keep the connection alive: To maintain a long-lived connection with the server, set the heartbeat parameter to
true. The connection to the server then stays open even when the audio contains no sound for a long time. - Model rate limits: When you call the model API, note the model's Rate limiting rules.
Core usage: Context biasing (Qwen3-ASR-Flash-Realtime)
By providing context, you can optimize the recognition of domain-specific vocabulary, such as names, places, and product terms.
Length limit: The context content cannot exceed 10,000 tokens.
Usage:
- WebSocket API: Set the
session.input_audio_transcription.corpus.textparameter in the session.update event. - Python SDK: Set the
corpus_textparameter. - Java SDK: Set the
corpusTextparameter.
- Hotword lists in various separator formats, such as Hotword 1, Hotword 2, Hotword 3, Hotword 4
- Text paragraphs or chapters of any format and length
- Mixed content: Any combination of word lists and paragraphs
- Irrelevant or meaningless text, including garbled text. The feature is highly fault-tolerant and is almost never negatively affected by irrelevant text.
| Without context enhancement | With context enhancement |
|---|---|
| Without context enhancement, some investment bank names may be misrecognized. For example, "Bird Rock" should be "Bulge Bracket". Recognition result: "What internal jargon from the investment banking circle do you know? First, the nine major foreign investment banks, Bird Rock, BB..." | With context enhancement, investment bank names are recognized correctly. Recognition result: "What internal jargon from the investment banking circle do you know? First, the nine major foreign investment banks, the Bulge Bracket, BB..." |
- Word lists:
- Word list 1:
- Word list 2:
- Word list 3:
- Natural language:
- Natural language with interference: Some text is irrelevant to the recognition content, such as the names in the example below.
Core usage: Sensitive word filtering (Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime)
Sensitive word filtering replaces or removes sensitive words in the recognition result. Use it for call-center quality inspection, content compliance, subtitle review, and similar scenarios.
Supported models: Qwen-Audio-3.0-ASR-Flash-Streaming and Fun-ASR-Realtime only.
Limit: You can set up to 32 sensitive words.
Default behavior: When the special_word_filter parameter is not passed, no sensitive words are filtered.
How to configure: special_word_filter is a JSON object with three subfields:
-
filter_with_signed.word_list: A string array that lists the sensitive words to replace with an equal-length string of*characters. For example, with["test"], "Help me test it" becomes "Help me **** it". -
filter_with_empty.word_list: A string array that lists the sensitive words to remove entirely from the result. For example, with["start"], "Is the game about to start" becomes "Is the game about to". -
system_reserved_filter: A boolean that defaults tofalse. It determines whether sensitive word filtering is enabled.
API reference
- Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime
- Qwen3-ASR-Flash-Realtime
- Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime real-time speech recognition API reference
- AOQ Client SDK (for Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime)
Interaction flow (Qwen3-ASR-Flash-Realtime)
Qwen real-time speech recognition streams audio over WebSocket. Two modes are available: VAD mode (default) and Manual mode.
URL
Replace <model_name> with your model name.
Headers
VAD mode (default)
The server detects speech boundaries and segments sentences. The client streams audio, and the server returns results when each sentence ends. Best for conversations and meeting transcription.
Enable: Set session.turn_detection in session.update.
-
The client sends
input_audio_buffer.appendto add audio to the buffer. -
The server returns
input_audio_buffer.speech_startedwhen it detects speech.If the client sendssession.finishbefore this event, the server returnssession.finishedand the client must disconnect. -
The client continues sending
input_audio_buffer.append. -
After all audio is sent, the client sends
session.finishto end the session. -
The server returns
input_audio_buffer.speech_stoppedwhen it detects the end of speech. -
The server returns
input_audio_buffer.committed. -
The server returns
conversation.item.created. -
The server returns
conversation.item.input_audio_transcription.textwith real-time transcription results. -
The server returns
conversation.item.input_audio_transcription.completedwith the final transcription result. -
The server returns
session.finishedwhen recognition completes. The client must then disconnect.
Manual mode
The client controls sentence segmentation by sending audio for a complete sentence, then sending input_audio_buffer.commit. Best when the client knows sentence boundaries, for example in chat app voice messages.
Enable: Set session.turn_detection to null in session.update.
-
The client sends
input_audio_buffer.appendto add audio to the buffer. -
The client sends
input_audio_buffer.committo create a new user message. -
The client sends
session.finishto end the session. -
The server returns
input_audio_buffer.committed. -
The server returns
conversation.item.input_audio_transcription.textwith real-time transcription results. -
The server returns
conversation.item.input_audio_transcription.completedwith the final transcription result. -
The server returns
session.finishedwhen recognition completes. The client must then disconnect.
Alternative: Use Qwen-Omni
You can also use Qwen-Omni (qwen3-omni-flash-realtime) for real-time speech recognition via WebSocket. Omni is an LLM that understands audio — you provide domain context through the system prompt instead of hotword lists.
When to use Omni for ASR: Clean speech inputs (microphone, voice calls) where you need domain-specific terminology handling via prompt.
When to use dedicated ASR models instead: Noisy or mixed audio (meetings with background music, videos with sound effects), or when you need hotwords, speaker diarization, or timestamps.
Qwen-Omni interprets all audio, not just speech. Music, typing, or ambient noise may produce descriptions instead of transcription. For mixed audio, preprocess with VAD to isolate speech, or use a dedicated ASR model.
Qwen-Omni-Realtime uses WebSocket for bidirectional streaming. For the full API and SDK reference, see Realtime conversation.