This topic describes the parameters and interfaces of the Python SDK for the Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime real-time speech recognition model.
User guide: For model descriptions and selection guidance, see Speech-to-text.
The Recognition class provides interfaces for both non-streaming and bidirectional streaming calls. Choose the call method that fits your needs:
Submit a single real-time speech recognition task and get the recognition result synchronously by passing in a local file.
Instantiate a Recognition class, bind request parameters, and call
Submit a single real-time speech recognition task and stream the real-time recognition results by implementing the callback interface.
Set request parameters through the constructor (
Pass the following parameters as keyword arguments to the
Example:
Import
During a bidirectional streaming call, the server returns key process information and data to the client through callbacks. Implement the callback methods to handle the information and data returned by the server.
The members of the Sentence class are as follows:
The members of the Word class are as follows:
If you encounter errors, see Error codes for troubleshooting.
If the issue persists, join the developer community to report your issue and provide the Request ID for further investigation.
Set the
Use FFmpeg. For more usage, see the FFmpeg official website.
There are two ways to recognize a local file:
Prerequisites
- The service is activated and you have obtained an API key. To guard against security risks caused by code leaks, configure the API key as an environment variable, rather than hard-coding it in your code.
- Install the latest DashScope SDK.
Quick start
The Recognition class provides interfaces for both non-streaming and bidirectional streaming calls. Choose the call method that fits your needs:
- Non-streaming call: Recognizes a local file and returns the complete result in a single response. Suitable for processing pre-recorded audio.
- Bidirectional streaming call: Recognizes an audio stream directly and outputs results in real time. The audio stream can come from an external device, such as a microphone, or be read from a local file. Suitable for scenarios that require immediate feedback.
Non-streaming call
Submit a single real-time speech recognition task and get the recognition result synchronously by passing in a local file.
Instantiate a Recognition class, bind request parameters, and call call to run recognition or translation and get the final recognition result (RecognitionResult).
View the full example
View the full example
Bidirectional streaming call
Submit a single real-time speech recognition task and stream the real-time recognition results by implementing the callback interface.
1
Start streaming speech recognition
Instantiate a Recognition class, bind request parameters and a Callback interface (RecognitionCallback), and call the
start method to start streaming speech recognition.2
Stream the audio
Call the
send_audio_frame method of the Recognition class in a loop to send the binary audio stream to the server in segments. The stream is read from a local file or a device, such as a microphone.While the audio is being sent, the server returns recognition results to the client in real time through the on_event method of the Callback interface (RecognitionCallback).Send about 100 ms of audio per frame, and keep each frame between 1 KB and 16 KB.3
End the task
Call the
stop method of the Recognition class to end speech recognition.This method blocks the current thread until the on_complete or on_error callback of the Callback interface (RecognitionCallback) is triggered.View the full example
View the full example
- Recognize microphone speech
- Recognize a local audio file
Request parameters
Set request parameters through the constructor (__init__) of the Recognition class.
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | str | Yes | The model name. The Qwen-Audio-3.0-ASR-Flash-Streaming and Fun-ASR-Realtime model series are supported. For details, see Supported models and regions. |
| sample_rate | int | Yes | The sample rate, in Hz. 8 kHz models support only 8000 Hz; other models support any sample rate. |
| format | str | Yes | The audio format. Valid values: pcm, wav, mp3, opus, speex, aac, amr. opus/speex: Must use Ogg encapsulation. wav: Must use PCM encoding. amr: Only the AMR-NB type is supported. |
| vocabulary_id | str | No | The ID of a precompiled hot word list. Generate this ID in advance by calling the create hot word list API. Pass the ID during recognition to use the hot words in the list. Suitable for scenarios where the vocabulary is known and relatively stable, and where you need to reuse the same word list across requests. For usage details, see Precompiled hotwords. |
| vocabulary | dict | No | Instant hot words. Passed as key-value pairs, where the key is the hot word text (string) and the value is the hot word weight (integer). No hot word list needs to be created in advance. The weight ranges from [1, 5] or is set to 50: a value in [1, 5] makes the model more likely to output the word as the value increases; a value of 50 designates a super hot word, which greatly improves recall, but the number of super hot words cannot exceed 50. Suitable for temporary, session-level hot word optimization. When configured together with precompiled hot words, only the instant hot words take effect. For usage details, see Instant hotwords. Only qwen-audio-3.0-asr-flash-streaming supports instant hot words.vocab = {"John Smith": 5, "Jane Doe": 5} recognition = Recognition(model='qwen-audio-3.0-asr-flash-streaming', format='wav', sample_rate=16000, vocabulary=vocab, callback=None) |
| semantic_punctuation_enabled | bool | No | Whether to enable semantic segmentation. Default: False.
|
| max_sentence_silence | int | No | The VAD silence threshold for segmentation, in ms. When the silence after a segment of speech exceeds this threshold, the system determines that the sentence has ended. When semantic_punctuation_enabled is set to true, this parameter is not used as the criterion for returning sentence_end, but setting it too low may affect recognition performance. Default value: 1300. Valid values: [200, 6000]. |
| multi_threshold_mode_enabled | bool | No | Takes effect only when semantic_punctuation_enabled is false. |
| punctuation_prediction_enabled | bool | No | Whether to automatically add punctuation to recognition results:
|
| heartbeat | bool | No | Whether to enable heartbeat packets. Default: False.
|
| language_hints | list[str] | No | The language of the audio to recognize. There is no default value; if not set, the model detects the language automatically. For the Qwen-Audio-3.0-ASR-Flash-Streaming model series, you can set up to 4 values; if you set more than 4, only the first 4 take effect. For the Fun-ASR-Realtime model series, you can set only 1 value; if you set multiple values, only the first one takes effect. Supported codes: |
| speech_noise_threshold | float | No | The threshold for distinguishing speech from noise, used to adjust the sensitivity of Voice Activity Detection (VAD). Valid values: [-1.0, 1.0].
|
| special_word_filter | str | No | Specifies the sensitive words to process during speech recognition, and supports setting different processing methods for different sensitive words. For details, see Sensitive word filtering. |
| callback | RecognitionCallback | No | Callback interface (RecognitionCallback). |
Method parameters
Pass the following parameters as keyword arguments to the call or start method of the Recognition instance.
| Parameter | Type | Required | Description |
|---|---|---|---|
| raw_input | dict | No | The input object used to pass in the conversation context. Context enhancement improves recognition accuracy for domain-specific terms. For usage, see Quick start. The context parameter is supported only by the qwen-audio-3.0-asr-flash-streaming, fun-asr-realtime, and fun-asr-realtime-2025-11-07 models.context key whose value is a list of messages (list[dict]). Each message contains the following fields:
Limits: Context messages of the input_text and text types are each limited to 5 messages. When the limit is exceeded, only the 5 most recent messages are retained. The total text length per context turn cannot exceed 400 characters, and any excess is truncated from the end.When you pass context, the messages in context must follow a specific order: context messages must be arranged by conversation turn, and within each turn, the user message (input_text type) must precede its corresponding assistant message (text type).This field requires SDK version 1.25.23 or later. Pass raw_input to the start or call method of the Recognition instance. |
Key interfaces
Recognition class
Import Recognition with from dashscope.audio.asr import *.
| Member method | Method signature | Description |
|---|---|---|
| call | def call(self, file: str, phrase_id: str = None, **kwargs) -> RecognitionResult | A non-streaming call based on a local file. This method blocks the current thread until all audio is read, and requires read permission on the file. The recognition result is returned as a RecognitionResult object. |
| start | def start(self, phrase_id: str = None, **kwargs) | Starts speech recognition. A callback-based streaming real-time recognition. This method does not block the current thread. Use it together with send_audio_frame and stop. |
| send_audio_frame | def send_audio_frame(self, buffer: bytes) | Pushes audio. Keep each pushed audio frame neither too large nor too small: about 100 ms per frame, between 1 KB and 16 KB. Recognition results are obtained through the on_event method of the Callback interface (RecognitionCallback). |
| stop | def stop(self) | Stops speech recognition. Blocks until the server finishes recognizing all received audio, then ends the task. |
| get_last_request_id | def get_last_request_id(self) | Gets the request_id. Available after the constructor is called (the object is created). |
| get_first_package_delay | def get_first_package_delay(self) | Gets the first-packet delay: the latency from sending the first audio packet to receiving the first recognition result. Use it after the task completes. |
| get_last_package_delay | def get_last_package_delay(self) | Gets the last-packet delay: the time from sending the stop command to receiving the last recognition result. Use it after the task completes. |
| get_response | def get_response(self) | Gets the last message. Use it to retrieve a task-failed error. |
Callback interface (RecognitionCallback)
During a bidirectional streaming call, the server returns key process information and data to the client through callbacks. Implement the callback methods to handle the information and data returned by the server.
View the example
View the example
| Method | Parameter | Return value | Description |
|---|---|---|---|
def on_open(self) -> None | None | None | Called immediately after the connection to the server is established. |
def on_event(self, result: RecognitionResult) -> None | result: RecognitionResult | None | Called when the server has a response. |
def on_complete(self) -> None | None | None | Called after all recognition results are returned. |
def on_error(self, result: RecognitionResult) -> None | result: RecognitionResult | None | Called when an error occurs. |
def on_close(self) -> None | None | None | Called after the server closes the connection. |
Response
Recognition result (RecognitionResult)
RecognitionResult represents the result of a single real-time recognition in a bidirectional streaming call, or the result of a non-streaming call.
| Member method | Method signature | Description |
|---|---|---|
| get_sentence | def get_sentence(self) -> Union[Dict[str, Any], List[Any]] | Gets the current recognized sentence and its timestamp information. A callback returns a single sentence, so this method returns Dict[str, Any]. For details, see Sentence (Sentence). |
| get_request_id | def get_request_id(self) -> str | Gets the request_id of the request. |
| is_sentence_end | @staticmethod def is_sentence_end(sentence: Dict[str, Any]) -> bool | Determines whether the given sentence has ended. This method checks whether the end_time field in sentence is None: a non-None end_time indicates that the sentence has ended. Call it as RecognitionResult.is_sentence_end(sentence), where sentence is the single-sentence dict returned by get_sentence(), not a boolean field on a Sentence instance. |
Sentence information (Sentence)
The members of the Sentence class are as follows:
| Parameter | Type | Description |
|---|---|---|
| begin_time | int | Sentence start time, in ms. |
| end_time | int | Sentence end time, in ms. |
| text | str | Recognized text. |
| words | A list of Word-level timestamp information (Word) | Word-level timestamp information. |
Word-level timestamp information (Word)
The members of the Word class are as follows:
| Parameter | Type | Description |
|---|---|---|
| begin_time | int | Word start time, in ms. |
| end_time | int | Word end time, in ms. |
| text | str | The word. |
| punctuation | str | The punctuation. |
Error codes
If you encounter errors, see Error codes for troubleshooting.
If the issue persists, join the developer community to report your issue and provide the Request ID for further investigation.
FAQ
Features
Q: How do I keep the connection alive during long periods of silence?
Set the heartbeat request parameter to true, and keep sending silent audio to the server.
Silent audio is content in an audio file or stream that contains no sound signal. You can generate silent audio in several ways, such as using audio editing software like Audacity or Adobe Audition, or command-line tools like FFmpeg.
Q: How do I convert audio to a supported format?
Use FFmpeg. For more usage, see the FFmpeg official website.
Q: How do I recognize a local file (recording)?
There are two ways to recognize a local file:
- Pass the local file path directly: This way returns the complete result only after recognition finishes, so it isn't suitable for scenarios that need immediate feedback. See Non-streaming call, and pass the file path to the
callmethod of the Recognition class to recognize the recording directly. - Convert the local file to a binary stream for recognition: This way recognizes the file while streaming results, so it suits scenarios that need immediate feedback. See Bidirectional streaming call, and send the binary stream to the server for recognition through the
send_audio_framemethod of the Recognition class.
Troubleshooting
Q: Why can't the speech be recognized (no recognition result)?
-
Check that the audio format (
format) and sample rate (sampleRate/sample_rate) in the request parameters are correct and meet the parameter constraints. Common errors include:- The audio file has a .wav extension but is actually in MP3 format, while the
formatrequest parameter is set to mp3 (incorrect parameter setting). - The audio sample rate is 3600 Hz, but the
sampleRate/sample_raterequest parameter is set to 48000 (incorrect parameter setting).
- The audio file has a .wav extension but is actually in MP3 format, while the
- If none of the checks above reveal a problem, add custom hotwords to improve recognition of specific terms.