Prerequisites
- The service is activated and Obtain an API key. To guard against security risks caused by code leaks, Configure API key as an environment variable, rather than hard-coding it in your code.
- Install the latest DashScope SDK.
Quick start
Use the same examples for the models below. Replace the model ID using this table.
| Model | Model ID in the example |
|---|---|
| Qwen-Audio-ASR-Streaming | qwen-audio-3.1-asr-flash-streamingFor microphone input, use qwen-audio-3.0-asr-flash-streaming. |
| Qwen-Audio-ASR-Message | qwen-audio-3.1-asr-flash-messageSupports only a sample rate of 16000 Hz. |
| Fun-ASR-Realtime | fun-asr-realtime |
client.audio.asr) provides interfaces for both non-streaming and bidirectional streaming calls. Choose the call method that fits your needs:
- Non-streaming call (
recognize_file): Recognizes a local file. The SDK automatically sends the audio in chunks and drives the task to completion. Suitable for processing pre-recorded audio. - Bidirectional streaming call (
recognizesession): 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
- Bidirectional streaming call
recognize_file method of the core resource (client.audio.asr) to bind the request parameters and pass in the local file path, then iterate the server events to get the recognition results.Request parameters
Qwen-Audio-ASR-Streaming
Shared reference
See the current Qwen-Audio-ASR-Streaming Python SDK reference.
Set request parameters through the recognize/recognize_file methods of the core resource (client.audio.asr): model, format, sample_rate, and vocabulary_id are named parameters, and the remaining parameters (such as language_hints) are passed in through the parameters dict.
| Parameter | Type | Required | Description |
|---|---|---|---|
model | str | Yes | The model name. |
sample_rate | int | Yes | The sample rate in Hz. Any sample rate is supported. |
format | str | Yes | The audio format.Valid values:
|
keep_dialect | bool | No | Supported by qwen-audio-3.1-asr-flash-streaming only. Defaults to false, which transcribes dialects into standard Chinese. Set to true to preserve dialect expressions. Pass as a keyword argument with the same name. See Client events for details. |
vad_model | str | No | Supported by qwen-audio-3.1-asr-flash-streaming only. Set to near_meeting_16k (near-field) or far_field_meeting_16k (far-field, default). Pass as a keyword argument with the same name. See Client events for details. |
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 instant and precompiled hotwords are configured together, the system merges both sets. If the merged set contains more than 2000 hotwords, the system randomly selects 2000 to use. For usage details, see Instant hotwords.Example: |
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.Default value: 800.Valid values: [200, 6000]. |
multi_threshold_mode_enabled | bool | No | Whether to enable multi-threshold mode. When enabled, it prevents VAD segmentation from producing segments that are too long.Default: 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.You can set up to 4 values. If you set more, only the first 4 take effect.
Click to view the supported language 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].Value descriptions:
|
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. |
input keyword argument of the recognize/recognize_file methods.
| Parameter | Type | Required | Description |
|---|---|---|---|
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 dict must include a context key whose value is a list of messages (list[dict]). Each message contains the following fields:
This field requires SDK version 2.0.1 or later. |
Qwen-Audio-ASR-Message
Shared reference
See the current Qwen-Audio-ASR-Message Python SDK reference.
Set request parameters through the recognize/recognize_file methods of the core resource (client.audio.asr): model, format, sample_rate, and vocabulary_id are named parameters, and other parameters such as language_hints are passed in through the parameters dictionary.
| Parameter | Type | Required | Description |
|---|---|---|---|
model | str | Yes | The model name. Set to qwen-audio-3.1-asr-flash-message. |
sample_rate | int | Yes | The sample rate, in Hz. Only16000 Hz is supported. |
format | str | Yes | The audio format. Valid values:
|
disfluency_removal_enabled | bool | No | Whether to filter filler words and polish the output. Defaults to false. Set to true to enable this feature. Pass as a keyword argument with the same name. |
intermediate_result_enabled | bool | No | Whether to return intermediate streaming results. Defaults to false. Set to true to return intermediate streaming results. Pass as a keyword argument with the same name. |
keep_dialect | bool | No | Defaults to false, which transcribes dialects into standard Chinese. Set to true to preserve dialect expressions. Pass as a keyword argument with the same name. See Client events for details.This parameter applies only to final results (sentence_end=true) and is not supported for intermediate results (sentence_end=false). |
vad_model | str | No | Set to near_meeting_16k (near-field) or far_field_meeting_16k (far-field, default). Pass as a keyword argument with the same name. See Client events for details. |
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 instant and precompiled hotwords are configured together, the system merges both sets. If the merged set contains more than 2000 hotwords, the system randomly selects 2000 to use. For usage details, see Instant hotwords.Example: |
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.You can set up to 4 values. If you set more, only the first 4 take effect.
Click to view the supported language codes
sentence_end=true) and is not supported for intermediate results (sentence_end=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. Default value: 800.Valid values: [200, 6000]. |
heartbeat | bool | No | Whether to enable heartbeat packets. Default: False.
|
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].Value descriptions:
|
input keyword argument of the recognize/recognize_file methods.
| Parameter | Type | Required | Description |
|---|---|---|---|
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 dict must include acontext key whose value is a list of messages (list[dict]). Each message contains the following fields:
This field was introduced in SDK 1.25.23 and is already included in version 2.0.1 and later. |
Fun-ASR-Realtime
Shared reference
See the current Fun-ASR-Realtime Python SDK reference.
Set request parameters through the recognize/recognize_file methods of the core resource (client.audio.asr): model, format, sample_rate, and vocabulary_id are named parameters, and the remaining parameters (such as max_sentence_silence and language_hints) are passed in through the parameters dictionary.
| Parameter | Type | Required | Description |
|---|---|---|---|
model | str | Yes | The model name. |
sample_rate | int | Yes | The sample rate, in Hz.Valid values: 8 kHz models support only 8000 Hz; other models support any sample rate. |
format | str | Yes | The audio format.Valid values:
|
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. |
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.Default value: 1300.Valid values: [200, 6000]. |
multi_threshold_mode_enabled | bool | No | Whether to enable multi-threshold mode. When enabled, it prevents VAD segmentation from producing segments that are too long.Default: 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.You can set 1 value. If you set more, only the first value takes effect.
Click to view the supported language 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].Value descriptions:
|
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. |
input keyword argument of the recognize/recognize_file methods.
| Parameter | Type | Required | Description |
|---|---|---|---|
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 Improve recognition accuracy.The dict must include a context key whose value is a list of messages (list[dict]). Each message contains the following fields:
This field requires SDK version 2.0.1 or later. |
API reference
Qwen-Audio-ASR-Streaming / Fun-ASR-Realtime
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. |
Qwen-Audio-ASR-Streaming
Key interfaces
Core resource (client.audio.asr)
Real-time speech recognition is mounted on the client.audio.asr resource: recognize creates a bidirectional streaming recognition session (Recognition), and recognize_file recognizes a local file in one shot.
| Member method | Method signature | Description |
|---|---|---|
| recognize | Creates a bidirectional streaming recognition session. Entering the with context automatically calls start to establish the connection and submit the task.Sending audio and consuming events must run concurrently (use it together with send_audio_frame, events()/results(), and stop). | |
| recognize_file | A non-streaming call based on a local file: automatically sends the audio in chunks and drives the task to completion, yielding server events one by one. This method requires read permission on the file. | |
start | Starts speech recognition: establishes the connection, submits the task, and waits for task-started. It is called automatically when entering the with context; audio can be sent only after a successful start. | |
send_audio_frame | 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 event iteration (events()/results()). | |
stop | Stops speech recognition: it only notifies the server that the input has ended. The receiver thread must keep consuming events() until the task-finished event. | |
| events / results | Iterates server events: events() yields raw event dicts (recognition text is in payload.output.sentence); results() yields only recognition result frames and returns typed recognition result (RecognitionResult) objects (heartbeat frames filtered out). | |
| close | Closes the recognition session. Called automatically when exiting the with context. | |
| request_id / first_package_delay / last_package_delay / last_response | Gets the request_id, first-packet delay (latency from sending the first audio packet to receiving the first recognition result), and last-packet delay (time from sending the stop command to receiving the last recognition result). Use them after the task completes; last_response is the raw message most recently read successfully, which you can use to retrieve a task-failed error. They remain readable after the session is closed. |
Event iteration (events()/results())
During a bidirectional streaming call, the server returns key process information and data to the client through events. In the receiver thread, iterate the session's events() (raw event dicts) or results() (typed recognition result frames) to handle the information and data returned by the server.
| Event/iteration method | Output | Return value | Description |
|---|---|---|---|
task-started event | None | Read internally by start() and saved in last_response when it returns; not yielded again by events(). | |
event: server event dict | Iterator | Yields events whenever the server has a response. Recognition results are in payload.output.sentence and may be heartbeat or empty-text events, which the application can ignore as needed. Keep a single receiver thread consuming it; do not create multiple concurrent readers. | |
result: recognition result (RecognitionResult) | Iterator | Yields only recognition result frames (heartbeat frames filtered out); the iteration ends after all recognition results are returned. | |
DashScopeError exception | None | Raised in the sending/receiving thread when an error occurs; catch it with try/except. | |
task-finished event | None | Yielded by events() after the server completes all recognition; the iteration then ends. You must still read this event after calling stop(). |
Response
Recognition result (RecognitionResult)
RecognitionResult represents a single recognition result frame yielded by the session's results() iteration (usable in both bidirectional streaming calls and non-streaming calls; events() yields raw event dicts, so use results() if you need this typed view).
| Member method | Method signature | Description |
|---|---|---|
get_sentence | Gets the current recognized sentence and its timestamp information. This method returns Dict[str, Any] (single-sentence information).For details, see Sentence (Sentence). | |
request_id | The request_id of the current event. | |
is_sentence_end | Determines whether the current sentence has ended. This method checks whether the end_time field in the single-sentence information returned by get_sentence() is None: a non-None end_time indicates that the sentence has ended. |
Qwen-Audio-ASR-Message
Key interfaces
Core resource (client.audio.asr)
The real-time speech recognition capability is mounted on the client.audio.asr resource: recognize creates a bidirectional streaming recognition session (Recognition), and recognize_file performs one-shot recognition on a local file.
| Member method | Method signature | Description |
|---|---|---|
| recognize | Creates a bidirectional streaming recognition session. Entering the with context automatically calls start to establish the connection and submit the task.Sending audio and consuming events must run concurrently (use it together with send_audio_frame, events()/results(), and stop). | |
| recognize_file | A non-streaming call based on a local file: it automatically sends the audio in chunks, drives the task to completion, and yields server events one by one. This method requires read permission on the file. | |
| start | Starts speech recognition: establishes the connection, submits the task, and waits for task-started. It is called automatically when the with context is entered, and audio can only be sent after it succeeds. | |
| send_audio_frame | 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 event iteration (events()/results()). | |
| stop | Stops speech recognition: it only notifies the server that the input is finished; the receiver thread must keep consuming events() until the task-finished event. | |
| events / results | Iterates server events: events() yields raw event dicts (the recognized text is in payload.output.sentence); results() yields only recognition result frames and returns typed Recognition result (RecognitionResult) objects (heartbeat frames are filtered out). | |
| close | Closes the recognition session. Called automatically when the with context is exited. | |
| request_id / first_package_delay / last_package_delay / last_response | Gets the request_id, the first-packet delay (the latency from sending the first audio packet to receiving the first recognition result), and the last-packet delay (the time from sending the stop command to the last recognition result arriving). Use them after the task completes. last_response is the last successfully read raw message, which you can use to retrieve a task-failed error. They remain readable after the session is closed. |
Update conversation context
Callupdate_context to update conversation context while a recognition task is running. The context is used to assist recognition of subsequent audio. This method requires DashScope Python SDK 2.0.1 or later.
- When to call: After entering the
withcontext (which automatically callsstart) to start streaming recognition, and before callingstop. - Parameter:
contextis a dictionary containing thepayload.inputobject of acontinue-taskevent, including thecontextfield. Do not add an extrapayloadorinputwrapper. - Supported models and parameter constraints: See continue-task.
recognition instance.
Event iteration (events()/results())
During a Bidirectional streaming call, the server returns key process information and data to the client through events. In the receiver thread, iterate the session's events() (raw event dicts) or results() (typed recognition result frames) to handle the information and data returned by the server.
| Event/iteration method | Output | Return value | Description |
|---|---|---|---|
task-started event | None | Read internally by start() and stored in last_response when it returns; it is not yielded again by events(). | |
event: a server event dict | Iterator | Yields events when the server responds. Recognition results are in payload.output.sentence and may be heartbeat or empty-text events, which applications can ignore as needed. Consume it with a single receiver thread; do not create multiple concurrent readers. | |
result: recognition result (RecognitionResult) | Iterator | Yields only recognition result frames (heartbeat frames are filtered out), and iteration ends after all recognition results are returned. | |
DashScopeError exception | None | Raised in the sending/receiving thread when an error occurs; catch it with try/except. | |
task-finished event | None | Yielded by events() after the server completes all recognition, after which iteration ends; you must still read this event after calling stop(). |
Response
Recognition result (RecognitionResult)
RecognitionResult represents a single recognition result frame yielded by the session's results() iteration (usable in both Bidirectional streaming calls and Non-streaming calls; events() yields raw event dicts—use results() if you need this typed view).
| Member method | Method signature | Description |
|---|---|---|
get_sentence | Gets the current recognized sentence and its timestamp information. This method returns Dict[str, Any] (a single sentence). For details, see Sentence (Sentence). | |
request_id | The request_id of the current event. | |
is_sentence_end | Determines whether the current sentence has ended. This method checks whether the end_time field in the single-sentence dict returned by get_sentence() is None: a non-None end_time indicates that the sentence has ended. |
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. |
Fun-ASR-Realtime
Key interfaces
Core resource (client.audio.asr)
Real-time speech recognition is mounted on the client.audio.asr resource: recognize creates a bidirectional streaming recognition session (Recognition), and recognize_file recognizes a local file in one call.
| Member method | Method signature | Description |
|---|---|---|
| recognize | Creates a bidirectional streaming recognition session. Entering the with context automatically calls start to establish the connection and submit the task.Sending audio and consuming events must run concurrently (use it together with send_audio_frame, events()/results(), and stop). | |
| recognize_file | A non-streaming call based on a local file: it automatically sends the audio in chunks and drives the task to completion, yielding server events one by one. This method requires read permission on the file. | |
| start | Starts speech recognition: establishes the connection, submits the task, and waits for task-started. Automatically called when entering the with context. Audio can be sent only after a successful start. | |
| send_audio_frame | 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 by iterating events()/results(). | |
| stop | Stops speech recognition: it only notifies the server that the input is finished. The receiver thread must keep consuming events() until the task-finished event. | |
| events / results | Iterates server events: events() yields raw event dicts (the recognition text is in payload.output.sentence); results() yields only recognition result frames, returning typed Recognition result (RecognitionResult) objects (heartbeat frames are filtered out). | |
| close | Closes the recognition session. Automatically called when exiting the with context. | |
| request_id / first_package_delay / last_package_delay / last_response | Gets the request_id, the first-packet delay (latency from sending the first audio packet to receiving the first recognition result), and the last-packet delay (time from sending the stop command to the last recognition result). Use them after the task completes. last_response is the last raw message successfully read, which you can use to retrieve task-failed errors. They remain readable after the session is closed. |
Event iteration (events()/results())
During a bidirectional streaming call, the server returns key process information and data to the client through events. In a receiver thread, iterate the session's events() (raw event dicts) or results() (typed recognition result frames) to handle the information and data returned by the server.
| Event/iteration method | Output | Return value | Description |
|---|---|---|---|
task-started event | None | Read internally by start() and saved in last_response when the start returns. It is not yielded again by events(). | |
event: server event dict | Iterator | Yields events when the server responds. The recognition result is in payload.output.sentence, which may be a heartbeat or empty-text event that applications can ignore as needed. Consume it from a single receiver thread and do not create multiple concurrent readers. | |
result: recognition result (RecognitionResult) | Iterator | Yields only recognition result frames (heartbeat frames are filtered out). The iteration ends after all recognition results are returned. | |
DashScopeError exception | None | Raised in the sending/receiving thread when an error occurs. You can catch it with try/except. | |
task-finished event | None | Yielded by events() when the server has completed all recognition, after which the iteration ends. You must still read this event after calling stop(). |
Response
Recognition result (RecognitionResult)
RecognitionResult represents a single recognition result frame yielded by iterating the session's results() (usable for both bidirectional streaming and non-streaming calls; events() yields raw event dicts—use results() if you need this typed view).
| Member method | Method signature | Description |
|---|---|---|
get_sentence | Gets the current recognized sentence and its timestamp information. This method returns Dict[str, Any] (single-sentence information).For details, see Sentence (Sentence). | |
request_id | The request_id corresponding to the current event. | |
is_sentence_end | Determines whether the current sentence has ended. This method checks whether the end_time field in the single-sentence information returned by get_sentence() is None: a non-None end_time indicates that the sentence has ended. |