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.
- 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.
Prerequisites
- An API key is Obtain an API key and set as an environment variable.
- To call the service through the DashScope SDK, install the latest SDK.
Quick start
The following examples show how to call the real-time speech recognition service through the DashScope SDK.
- Qwen-Audio-3.0-ASR-Flash-Streaming/ Fun-ASR -Realtime
- Qwen3-ASR-Flash-Realtime
- Paraformer
- Recognize speech from a microphone
- Recognize a local audio file
- Java
- Python
Recognition configuration
Qwen3-ASR-Flash-Realtime interaction modes
The Qwen3-ASR-Flash-Realtime Realtime API offers two interaction modes:
- VAD mode (default): The server automatically detects the start and end of speech (segmentation). This mode suits real-time conversations, meeting notes, and similar scenarios. To enable it, configure the
session.turn_detectionparameter (enabled by default). - Manual mode: The client controls segmentation by sending
input_audio_buffer.commit. This mode suits scenarios that require explicit control over when audio is sent, such as sending a voice message in a chat app. To enable it, setsession.turn_detectionto null.
- WebSocket: Set the
turn_detectionfield in asession.updateevent.
- Python SDK: Set the
enable_turn_detectionparameter in theupdate_sessionmethod.
- Java SDK: Set the
enableTurnDetectionparameter throughOmniRealtimeConfig.builder().
VAD segmentation configuration
Voice Activity Detection (VAD) determines when a continuous segment of speech ends, which triggers the final recognition result event. All three model families enable server-side VAD by default, but their parameter names and tuning granularity differ:
- Qwen-Audio-3.0-ASR-Flash-Streaming / Fun-ASR-Realtime / Paraformer: Configured through
max_sentence_silence(the VAD silence threshold for segmentation, in milliseconds). When the silence after a segment of speech exceeds this threshold, the system treats the sentence as complete. - Qwen3-ASR-Flash-Realtime: Configured through
session.turn_detection, which includessilence_duration_ms(the silence duration threshold that ends a turn when exceeded; server default800, with400recommended for conversation and chat scenarios that need fast segmentation) andthreshold(VAD detection sensitivity; server default0.2). Qwen3-ASR-Flash-Realtime also supports Manual mode, which disables VAD and uses client-side commit for segmentation. For details, see Qwen3-ASR-Flash-Realtime interaction modes above.
max_sentence_silence in Qwen-Audio-3.0-ASR-Flash-Streaming / Fun-ASR-Realtime / Paraformer, and silence_duration_ms in Qwen3-ASR-Flash-Realtime. For the full field definitions, see API reference.
Advanced features
Improve accuracy with hotwords
Use hotwords to improve recognition accuracy for specific terms, such as brand names, personal names, and proper terminology.
For detailed hotword configuration and usage, see Improve recognition accuracy.
Improve accuracy with context enhancement
Context enhancement passes conversation history or domain terminology to the ASR model to significantly improve transcription accuracy for proper terms. For detailed usage and result examples, see Context enhancement.
Get timestamps
The Qwen-Audio-3.0-ASR-Flash-Streaming, Fun-ASR-Realtime, and Paraformer model families output timestamps at both the sentence level and the word level by default, which supports subtitle alignment, keyword highlighting, karaoke-style read-along, and similar scenarios. Qwen3-ASR-Flash-Realtime (qwen3-asr-flash-realtime) does not currently return timestamps. If you need timestamps, use Qwen-Audio-3.0-ASR-Flash-Streaming, Fun-ASR-Realtime, or Paraformer. For file transcription, the Qwen ASR recording-file transcription model qwen3-asr-flash-filetrans supports word-level timestamps. For details, see Non-real-time speech recognition.
Timestamps are returned in milliseconds at two levels:
- Sentence level:
payload.output.sentence.begin_timeandpayload.output.sentence.end_timemark the start and end of a full sentence in the audio. In an intermediate result,end_timemay benulland is filled with the final value when the sentence ends (sentence_end = true). - Word level: The
payload.output.sentence.wordsarray, where each element containsbegin_time,end_time,text(the word or character text), andpunctuation(the punctuation that follows the word, or an empty string if none).
Emotion recognition
Qwen3-ASR-Flash-Realtime and some Paraformer models can include the speaker's emotional state in the transcription result, but the two differ in output granularity and in how the feature is enabled.
Qwen3-ASR-Flash-Realtime (qwen3-asr-flash-realtime): Always on, no configuration required. The emotion is returned through a top-level emotion field in both the conversation.item.input_audio_transcription.text and conversation.item.input_audio_transcription.completed events. The value is one of seven fine-grained emotions: surprised, neutral, happy, sad, disgusted, angry, and fearful.
payload.output.sentence.emo_tag and payload.output.sentence.emo_confidence. The value is one of three polarities: positive (such as happy or satisfied), negative (such as angry or subdued), and neutral (no clear emotion). The confidence ranges from 0.0 to 1.0.
Emotion recognition is returned only when all of the following conditions are met:
- The model is
paraformer-realtime-8k-v2. - Semantic segmentation is off:
semantic_punctuation_enabled = false(false is the default, so no special setting is needed). - The result is returned only in the sentence-end event, where
sentence_end = true.
semantic_punctuation_enabled to true. This enables semantic segmentation and no longer returns the emo_tag and emo_confidence fields.
The field names above follow the WebSocket JSON paths. Different SDKs expose these fields with their own naming conventions (dictionary keys, object properties, getter methods, and so on). For the complete field mapping, see the API reference for each SDK.
For the full field definitions, value constraints, and examples, see API reference.
Sensitive word filtering
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.
Call the raw WebSocket protocol
The following examples show how to connect directly to the server over the raw WebSocket protocol, for scenarios that do not use the DashScope SDK. Each example is a minimal, runnable implementation. For the WebSocket protocol, see the API reference of each model.
Click to view raw WebSocket protocol examples
Click to view raw WebSocket protocol examples
- Qwen-Audio-3.0-ASR-Flash-Streaming/ Fun-ASR-Realtime
- Qwen3-ASR-Flash-Realtime
- Paraformer
- Python
- Java
- Node.js
- C#
- PHP
- Go
websocket.py. This name conflicts with the websocket library and causes the following error: AttributeError: module 'websocket' has no attribute 'WebSocketApp'. Did you mean: 'WebSocket'?.Apply in production
Reuse connections (WebSocket)
The WebSocket connections for Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime and Paraformer support reuse: after one recognition task finishes, you can start the next task without reestablishing the connection.
Reuse flow: The client sends finish-task. After the server returns task-finished, the client can send run-task again to start a new task.
Qwen3-ASR-Flash-Realtime uses a session model and does not support connection reuse. Close the connection after each session ends.
For the events of each model, see the corresponding API reference.
High-concurrency best practices
The DashScope SDK includes a built-in pooling mechanism that reuses WebSocket connections and recognition objects, which avoids the overhead of frequent creation and destruction.
Click to view high-concurrency best practices
Click to view high-concurrency best practices
Prerequisites
- Obtain an API key
- The DashScope SDK is installed and meets the version requirement. We recommend that you install the latest version: Java SDK version 2.16.9 or later.
- Connection pool: The OkHttp3 connection pool integrated in the SDK manages and reuses the underlying WebSocket connections, which reduces network handshake overhead. This feature is enabled by default.
- Object pool: Built on
commons-pool2, the object pool maintains a set ofRecognitionobjects whose connections are already established. Borrowing an object from the pool eliminates the connection setup latency and significantly reduces first-packet latency.
Implementation steps
-
Add dependencies
Add dashscope-sdk-java and commons-pool2 to your dependency configuration file, based on your project's build tool.
The following examples show the configuration for Maven and Gradle:
- Maven
- Gradle
- Open the
pom.xmlfile of your Maven project. - Add the following dependencies inside the
<dependencies>tag.
- Save the
pom.xmlfile. - Run a Maven command (such as
mvn clean installormvn compile) to update the project dependencies.
-
Configure the connection pool
Configure the key connection pool parameters through environment variables:
Environment variable
Description
DASHSCOPE_CONNECTION_POOL_SIZE
The connection pool size.
Recommended value: at least twice the peak concurrency.
Default value: 32.
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS
The maximum number of asynchronous requests.
Recommended value: the same as
DASHSCOPE_CONNECTION_POOL_SIZE.Default value: 32.
DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST
The maximum number of asynchronous requests per host.
Recommended value: the same as
DASHSCOPE_CONNECTION_POOL_SIZE.Default value: 32.
-
Configure the object pool
Configure the object pool size through an environment variable:
Create the object pool with the following code:Environment variable
Description
RECOGNITION_OBJECTPOOL_SIZE
The object pool size.
Recommended value: 1.5 to 2 times the peak concurrency.
Default value: 500.
-
Borrow a Recognition object from the object pool
When the number of unreturned objects exceeds the object pool limit, the system creates additional
Recognitionobjects. These new objects must reestablish a WebSocket connection and cannot be reused.
-
Perform speech recognition
Call the call or streamCall method of the
Recognitionobject to perform speech recognition. - Return the Recognition object After the speech recognition task finishes, return the Recognition object so that it can be reused. Do not return objects with unfinished or failed tasks.
Complete code
Recommended configuration
The following configurations are based on test results from running only the Paraformer real-time speech recognition service on Alibaba Cloud servers of the specified specifications. Single-machine concurrency is the number of Paraformer real-time speech recognition tasks running at the same time (that is, the number of worker threads).Machine specification (Alibaba Cloud) | Max single-machine concurrency | Object pool size | Connection pool size |
|---|---|---|---|
4 vCPUs, 8 GiB | 100 | 500 | 2000 |
8 vCPUs, 16 GiB | 200 | 500 | 2000 |
16 vCPUs, 32 GiB | 400 | 500 | 2000 |
Resource management and error handling
-
Task succeeds: Call
GenericObjectPool.returnObject()to return the Recognition object to the pool for reuse. -
Task fails: When an exception thrown by the SDK or your business logic interrupts a task, perform the following two actions:
- Actively close the underlying WebSocket connection.
- Invalidate the object in the object pool to prevent it from being reused.
- When the service returns a TaskFailed error, no extra handling is required.
Warm-up and latency measurement
When you evaluate performance such as concurrent call latency for the DashScope Java SDK, we recommend that you run a sufficient warm-up before the formal test.Connection reuse mechanism
The DashScope Java SDK manages and reuses WebSocket connections through a global singleton connection pool. This mechanism works as follows:- On-demand creation: The SDK does not pre-create WebSocket connections at service startup. Instead, it establishes connections on demand at the first call.
-
Time-limited reuse: After a request completes, the connection stays in the pool for up to 60 seconds for reuse.
- If a new request arrives within 60 seconds, the SDK reuses the existing connection and avoids the overhead of a repeated handshake.
- If a connection stays idle for more than 60 seconds, the SDK closes it automatically to release resources.
Why warm-up matters
In the following scenarios, the connection pool might not have an active connection to reuse, so a request has to create a new connection:- The application has just started and has not made any calls yet.
- The service has been idle for more than 60 seconds, so pooled connections have closed due to timeout.
Recommended approach
Before you run a formal load test or measure latency, follow these warm-up steps:- Simulate the concurrency level of the formal test by sending a number of calls in advance (for example, for 1 to 2 minutes) to fully populate the connection pool.
- After you confirm that the connection pool has established and maintained enough active connections, start collecting the formal performance data.
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.
- 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.
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.
Supported models and regions
- Singapore
- China (Beijing)
- Qwen-Audio-3.0-ASR-Flash-Streaming: qwen-audio-3.0-asr-flash-streaming
- Fun-ASR-Realtime: fun-asr-realtime (stable version, currently equivalent to fun-asr-realtime-2025-11-07), fun-asr-realtime-2025-11-07 (snapshot version)
- Qwen3-ASR-Flash-Realtime: qwen3-asr-flash-realtime (stable version, currently equivalent to qwen3-asr-flash-realtime-2025-10-27), qwen3-asr-flash-realtime-2026-02-10 (latest snapshot version), qwen3-asr-flash-realtime-2025-10-27 (snapshot version)
API reference
- Real-time speech recognition - Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime API reference
- Real-time speech recognition - Qwen3-ASR-Flash-Realtime API reference
- Real-time speech recognition - Paraformer API reference
- AOQ client SDK (for Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime)
FAQ
Which audio formats does real-time speech recognition support?
The Qwen-Audio-3.0-ASR-Flash-Streaming, Fun-ASR-Realtime, and Paraformer models support the pcm, wav, mp3, opus, speex, aac, and amr formats. For the Qwen3-ASR-Flash-Realtime model, we recommend the pcm or opus format. Other formats (such as wav, aac, and amr) are accepted by the session.update validation layer, but the server-side decoding might fail. Confirm that the audio stream uses a recommended format before you send it.
What's the difference between the SDK and the WebSocket API, and how do I choose?
The DashScope SDK encapsulates details such as WebSocket connection management, authentication, and reconnection, which makes it a good fit for quick integration. Connecting directly to the WebSocket API provides finer-grained control and suits programming languages that the SDK does not cover or scenarios that require custom connection management. We recommend that you use the SDK first.
How do I improve recognition accuracy for proper nouns?
Use hotwords or context enhancement. For detailed configuration methods and usage notes, see Improve recognition accuracy.
What should I do when the connection drops frequently?
Implement client-side reconnection and enable the heartbeat parameter (heartbeat=true) to prevent the connection from dropping when there is no audio for a long time. For detailed fault-tolerance strategies, see Apply in production.