All Products
Search
Document Center

Alibaba Cloud Model Studio:Qwen-Audio-ASR / Fun-ASR Python SDK

Last Updated:Nov 19, 2026

Prerequisites

Quick start

Use the same examples for the models below. Replace the model ID using this table.

ModelModel ID in the example
Qwen-Audio-ASR-Streamingqwen-audio-3.1-asr-flash-streaming
For microphone input, use qwen-audio-3.0-asr-flash-streaming.
Qwen-Audio-ASR-Messageqwen-audio-3.1-asr-flash-message
Supports only a sample rate of 16000 Hz.
Fun-ASR-Realtimefun-asr-realtime

The core resource (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 (recognize session): 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.

Call the 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.

import os
import dashscope

# The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API Key: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # The following is the configuration for the Singapore (ap-southeast-1) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# Recognize a local audio file: recognize_file automatically sends the audio in chunks and drives the task to completion
for event in client.audio.asr.recognize_file(
        '{YOUR_AUDIO_FILE}',
        model='qwen-audio-3.1-asr-flash-streaming',
        format='wav',
        sample_rate=16000):
    payload = event.get('payload') or {}
    sentence = (payload.get('output') or {}).get('sentence') or {}
    if sentence.get('text') and not sentence.get('heartbeat'):
        print('Recognition result:', sentence['text'])

Bidirectional streaming call

Submit a single real-time speech recognition task and stream the real-time recognition results by iterating events.

  1. Start streaming speech recognition.

    Call the recognize method of the core resource (client.audio.asr) to create a recognition session and bind the request parameters, then enter the with context (which automatically calls the start method to establish the connection and submit the task) to start streaming speech recognition.

  2. Stream the audio.

    Call the session's send_audio_frame method 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.

    Sending and receiving must run concurrently: the receiver thread iterates the server events through the session's events() method, and recognition results are returned to the client in real time.

    Send about 100 ms of audio per frame, and keep each frame between 1 KB and 16 KB.

  3. End the task.

    Call the session's stop method to end speech recognition.

    This method only notifies the server that the input has ended; the receiver thread must keep consuming events() until the task-finished event to get the last recognition results and statistics. Errors at the WebSocket layer are raised as DashScopeError exceptions, which you can catch with try/except where you send or receive.

import os
import signal  # for keyboard events handling (press "Ctrl+C" to terminate recording)
import sys

import dashscope
import pyaudio
from concurrent.futures import ThreadPoolExecutor

mic = None
stream = None

# Set recording parameters
sample_rate = 16000  # sampling rate (Hz)
channels = 1  # mono channel
dtype = 'int16'  # data type
format_pcm = 'pcm'  # the format of the audio data
block_size = 3200  # number of frames per buffer

# Real-time speech recognition event receiver
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('Recognition text: ', sentence['text'])
            if sentence.get('sentence_end'):
                print(
                    'Recognition sentence end, request_id:%s, usage:%s'
                    % (rec.request_id, rec.usage))

def signal_handler(sig, frame):
    print('Ctrl+C pressed, stop recognition ...')
    # Stop recognition
    recognition.stop()
    print('Recognition stopped.')
    print(
        '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
        .format(
            recognition.request_id,
            recognition.first_package_delay,
            recognition.last_package_delay,
        ))
    # Forcefully exit the program
    sys.exit(0)

# main function
if __name__ == '__main__':
    # The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
    # If you have not configured the environment variable, replace the following line with your Model Studio API Key: api_key="sk-xxx"
    client = dashscope.Client(
        api_key=os.environ.get('DASHSCOPE_API_KEY'),
        # The following is the configuration for the Singapore (ap-southeast-1) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
        workspace="{WorkspaceId}",
        region="ap-southeast-1",
    )

    # Call recognition service, you can customize the recognition parameters, like model, format,
    # sample_rate
    with client.audio.asr.recognize(
            model='qwen-audio-3.0-asr-flash-streaming',
            format=format_pcm,
            # 'pcm'、'wav'、'opus'、'speex'、'aac'、'amr', you can check the supported formats in the document
            sample_rate=sample_rate,
            # support 8000, 16000
    ) as recognition:
        # Open the microphone
        mic = pyaudio.PyAudio()
        stream = mic.open(format=pyaudio.paInt16,
                          channels=1,
                          rate=16000,
                          input=True)
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, recognition)
            try:
                # Send audio from the microphone until "Ctrl+C" is pressed
                while stream:
                    data = stream.read(3200, exception_on_overflow=False)
                    recognition.send_audio_frame(data)
                recognition.stop()
                receiver.result()
            finally:
                # close must run inside the pool context to unblock the receiver
                recognition.close()
        stream.stop_stream()
        stream.close()
        mic.terminate()
        stream = None
        mic = None
import os
import time
import dashscope
from concurrent.futures import ThreadPoolExecutor

# The API Key differs between the Singapore and Beijing regions. Get an API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
# If you have not configured the environment variable, replace the following line with your Model Studio API Key: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.environ.get('DASHSCOPE_API_KEY'),
    # The following is the configuration for the Singapore (ap-southeast-1) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

from datetime import datetime

def get_timestamp():
    now = datetime.now()
    formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
    return formatted_timestamp

# Real-time speech recognition event receiver
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print(get_timestamp() + ' Recognition text: ', sentence['text'])
        if sentence.get('sentence_end'):
            print(get_timestamp() +
                  'Recognition sentence end, request_id:%s, usage:%s'
                  % (rec.request_id, rec.usage))

with client.audio.asr.recognize(
        model='qwen-audio-3.1-asr-flash-streaming',
        format='wav',
        sample_rate=16000,
) as recognition:
    with ThreadPoolExecutor(max_workers=1) as pool:
        receiver = pool.submit(receive_events, recognition)
        try:
            audio_data: bytes = None
            f = open("{YOUR_AUDIO_FILE}", 'rb')
            if os.path.getsize("{YOUR_AUDIO_FILE}"):
                # Read all the file data into the buffer at once
                file_buffer = f.read()
                f.close()
                print("Start Recognition")

                # Send 3200 bytes from the buffer at a time
                buffer_size = len(file_buffer)
                offset = 0
                chunk_size = 3200

                while offset < buffer_size:
                    # Calculate the size of the data chunk to send this time
                    remaining_bytes = buffer_size - offset
                    current_chunk_size = min(chunk_size, remaining_bytes)

                    # Extract the current data chunk from the buffer
                    audio_data = file_buffer[offset:offset + current_chunk_size]

                    # Send the audio data frame
                    recognition.send_audio_frame(audio_data)
                    # Update the offset
                    offset += current_chunk_size

                    # Add a delay to simulate real-time transmission
                    time.sleep(0.1)

                recognition.stop()
                receiver.result()
            else:
                raise Exception(
                    'The supplied file was empty (zero bytes long)')
        finally:
            # close must run inside the pool context to unblock the receiver
            recognition.close()

print(
    '[Metric] requestId: {}, first package delay ms: {}, last package delay ms: {}'
    .format(
        recognition.request_id,
        recognition.first_package_delay,
        recognition.last_package_delay,
    ))

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.

ParameterTypeRequiredDescription
modelstrYesThe model name.
sample_rateintYes

The sample rate in Hz. Any sample rate is supported.

formatstrYesThe audio format.

Valid values:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

Importantopus/speex: Must use Ogg encapsulation.

wav: Must use PCM encoding.

amr: Only the AMR-NB type is supported.

keep_dialectboolNoSupported 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_modelstrNoSupported 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_idstrNoThe 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.

vocabularydictNoInstant 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:

import os
import dashscope

client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# Instant hot words are passed in through parameters
vocab = {"John Smith": 5, "Jane Doe": 5}
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.0-asr-flash-streaming',
    format='wav',
    sample_rate=16000,
    parameters={"vocabulary": vocab},
)
max_sentence_silenceintNoThe 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_enabledboolNo

Whether to enable multi-threshold mode. When enabled, it prevents VAD segmentation from producing segments that are too long.

Default: False.

punctuation_prediction_enabledboolNoWhether to automatically add punctuation to recognition results:
  • True (default): Yes. This value cannot be changed.
heartbeatboolNoWhether to enable heartbeat packets.

Default: False.

  • True: Keeps the connection to the server alive while silent audio is sent continuously.
  • False (default): Even when silent audio is continuously sent, the connection times out and closes after a period of time.

Silent audio refers to content in an audio file or data 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 using a command-line tool like FFmpeg.

This field requires SDK version 2.0.1 or later.

language_hintslist[str]NoThe 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

  • zh: Chinese
  • en: English
  • ja: Japanese
  • ko: Korean
  • vi: Vietnamese
  • th: Thai
  • id: Indonesian
  • ms: Malay
  • tl: Filipino
  • hi: Hindi
  • ar: Arabic
  • fr: French
  • de: German
  • es: Spanish
  • pt: Portuguese
  • ru: Russian
  • it: Italian
  • nl: Dutch
  • sv: Swedish
  • da: Danish
  • fi: Finnish
  • no: Norwegian
  • el: Greek
  • pl: Polish
  • cs: Czech
  • hu: Hungarian
  • ro: Romanian
  • bg: Bulgarian
  • hr: Croatian
  • sk: Slovak
speech_noise_thresholdfloatNoThe threshold for distinguishing speech from noise, used to adjust the sensitivity of Voice Activity Detection (VAD).

Valid values: [-1.0, 1.0].

Value descriptions:

  • The closer the value is to -1: The noise threshold decreases, so noise is more likely to be recognized as speech, which may cause more noise to be transcribed.
  • The closer the value is to +1: The noise threshold increases, so speech is more likely to be misjudged as noise, which may cause some speech to be filtered out.

This is an advanced configuration parameter. Adjusting it can significantly affect recognition results. Recommendations:

  • Thoroughly test and verify the results before adjusting.
  • Adjust in small increments based on the actual audio environment (a step of 0.1 is recommended).
special_word_filterstrNoSpecifies the sensitive words to process during speech recognition, and supports setting different processing methods for different sensitive words. For details, see Sensitive word filtering.

The following parameters are passed in through the input keyword argument of the recognize/recognize_file methods.

ParameterTypeRequiredDescription
inputdictNoThe 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:

  • role (str, required): The message role. user represents the recognition results from previous user turns or a domain-specific word list. assistant represents the large language model responses from previous turns.
  • content (list[dict], required): The list of message content. Each element contains type (str; set to input_text when role is user, and text when role is assistant) and text (str, the text content).

ImportantContext 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.

ImportantWhen 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).

NoteThis field requires SDK version 2.0.1 or later.

# Build the input to pass in
input_context = {
    "context": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Hello there"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, I am Qwen. How can I help you?"
                }
            ]
        }
    ]
}

# Pass it in through the input parameter when creating the recognition session
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-streaming',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

Qwen-Audio-ASR-Message

Shared reference

See the current Qwen-Audio-ASR-Message Python SDK reference.

ImportantAlibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

  • China (Beijing): from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from dashscope-intl.aliyuncs.com to {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

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.

ParameterTypeRequiredDescription
modelstrYesThe model name. Set to qwen-audio-3.1-asr-flash-message.
sample_rateintYes

The sample rate, in Hz.

Only 16000 Hz is supported.

formatstrYes

The audio format.

Valid values:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

Importantopus/speex: Must use Ogg encapsulation.

wav: Must use PCM encoding.

amr: Only the AMR-NB type is supported.

disfluency_removal_enabledboolNoWhether 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_enabledboolNoWhether 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_dialectboolNoDefaults 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_modelstrNoSet 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_idstrNo

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.

vocabularydictNo

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:

import os
import dashscope

client = dashscope.Client(api_key=os.getenv("DASHSCOPE_API_KEY"))

# Instant hot words are passed in through parameters
vocab = {"John Smith": 5, "Jane Doe": 5}
recognition = client.audio.asr.recognize(
    model='qwen-audio-3.1-asr-flash-message',
    format='wav',
    sample_rate=16000,
    parameters={"vocabulary": vocab},
)
language_hintslist[str]NoThe 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

  • zh: Chinese
  • en: English
  • ja: Japanese
  • ko: Korean
  • vi: Vietnamese
  • th: Thai
  • id: Indonesian
  • ms: Malay
  • tl: Filipino
  • hi: Hindi
  • ar: Arabic
  • fr: French
  • de: German
  • es: Spanish
  • pt: Portuguese
  • ru: Russian
  • it: Italian
  • nl: Dutch
  • sv: Swedish
  • da: Danish
  • fi: Finnish
  • no: Norwegian
  • el: Greek
  • pl: Polish
  • cs: Czech
  • hu: Hungarian
  • ro: Romanian
  • bg: Bulgarian
  • hr: Croatian
  • sk: Slovak

Pass it as a keyword argument with the same name.

This parameter applies only to final results (sentence_end=true) and is not supported for intermediate results (sentence_end=false).

max_sentence_silenceintNo

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].

heartbeatboolNo

Whether to enable heartbeat packets.

Default: False.

  • True: Keeps the connection to the server alive while silent audio is sent continuously.
  • False (default): Even when silent audio is continuously sent, the connection times out and closes after a period of time.

Silent audio refers to content in an audio file or data 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 using a command-line tool like FFmpeg.

This field was introduced in SDK 1.23.1 and is already included in version 2.0.1 and later.

speech_noise_thresholdfloatNo

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:

  • The closer the value is to -1: The noise threshold decreases, so noise is more likely to be recognized as speech, which may cause more noise to be transcribed.
  • The closer the value is to +1: The noise threshold increases, so speech is more likely to be misjudged as noise, which may cause some speech to be filtered out.

This is an advanced configuration parameter. Adjusting it can significantly affect recognition results. Recommendations:

  • Thoroughly test and verify the results before adjusting.
  • Adjust in small increments based on the actual audio environment (a step of 0.1 is recommended).

Pass the following parameters through the input keyword argument of the recognize/recognize_file methods.

ParameterTypeRequiredDescription
inputdictNo

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:

  • role (str, required): The message role. user represents the recognition results from previous user turns or a domain-specific word list. assistant represents the large language model responses from previous turns.
  • content (list[dict], required): The list of message content. Each element contains type (str; set to input_text when role is user, and text when role is assistant) and text (str, the text content).

ImportantContext 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.

ImportantWhen 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).

NoteThis field was introduced in SDK 1.25.23 and is already included in version 2.0.1 and later.

# Build the input to pass in
      input_context = {
          "context": [
              {
                  "role": "user",
                  "content": [
                      {
                          "type": "input_text",
                          "text": "Hello there"
                      }
                  ]
              },
              {
                  "role": "assistant",
                  "content": [
                      {
                          "type": "text",
                          "text": "Hello, I am Qwen. How can I help you?"
                      }
                  ]
              }
          ]
      }

      # Pass it in through the input parameter when creating the recognition session
      recognition = client.audio.asr.recognize(
          model='qwen-audio-3.1-asr-flash-message',
          format='wav',
          sample_rate=16000,
          input=input_context,
      )

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.

ParameterTypeRequiredDescription
modelstrYesThe model name.
sample_rateintYesThe sample rate, in Hz.

Valid values: 8 kHz models support only 8000 Hz; other models support any sample rate.

formatstrYesThe audio format.

Valid values:

  • pcm
  • wav
  • mp3
  • opus
  • speex
  • aac
  • amr

Importantopus/speex: Must use Ogg encapsulation.

wav: Must use PCM encoding.

amr: Only the AMR-NB type is supported.

vocabulary_idstrNoThe 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_silenceintNoThe 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_enabledboolNo

Whether to enable multi-threshold mode. When enabled, it prevents VAD segmentation from producing segments that are too long.

Default: False.

punctuation_prediction_enabledboolNoWhether to automatically add punctuation to recognition results:
  • True (default): Yes. This value cannot be changed.
heartbeatboolNoWhether to enable heartbeat packets.

Default: False.

  • True: Keeps the connection to the server alive while silent audio is sent continuously.
  • False (default): Even when silent audio is continuously sent, the connection times out and closes after a period of time.

Silent audio refers to content in an audio file or data 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 using a command-line tool like FFmpeg.

This field requires SDK version 2.0.1 or later.

language_hintslist[str]NoThe 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

  • fun-asr-realtime:

    • zh: Chinese
    • en: English
    • ja: Japanese
    • ko: Korean
    • vi: Vietnamese
    • th: Thai
    • id: Indonesian
    • ms: Malay
    • tl: Filipino
    • hi: Hindi
    • ar: Arabic
    • fr: French
    • de: German
    • es: Spanish
    • pt: Portuguese
    • ru: Russian
    • it: Italian
    • nl: Dutch
    • sv: Swedish
    • da: Danish
    • fi: Finnish
    • no: Norwegian
    • el: Greek
    • pl: Polish
    • cs: Czech
    • hu: Hungarian
    • ro: Romanian
    • bg: Bulgarian
    • hr: Croatian
    • sk: Slovak
  • fun-asr-realtime-2026-02-28:

    • zh: Chinese
    • en: English
    • ja: Japanese
  • fun-asr-flash-8k-realtime, fun-asr-flash-8k-realtime-2026-01-28:

    • zh: Chinese
speech_noise_thresholdfloatNoThe threshold for distinguishing speech from noise, used to adjust the sensitivity of Voice Activity Detection (VAD).

Valid values: [-1.0, 1.0].

Value descriptions:

  • The closer the value is to -1: The noise threshold decreases, so noise is more likely to be recognized as speech, which may cause more noise to be transcribed.
  • The closer the value is to +1: The noise threshold increases, so speech is more likely to be misjudged as noise, which may cause some speech to be filtered out.

This is an advanced configuration parameter. Adjusting it can significantly affect recognition results. Recommendations:

  • Thoroughly test and verify the results before adjusting.
  • Adjust in small increments based on the actual audio environment (a step of 0.1 is recommended).
special_word_filterstrNoSpecifies the sensitive words to process during speech recognition, and supports setting different processing methods for different sensitive words. For details, see Sensitive word filtering.

Pass the following parameters through the input keyword argument of the recognize/recognize_file methods.

ParameterTypeRequiredDescription
inputdictNoThe input object used to pass in the conversation context. Context enhancement improves recognition accuracy for domain-specific terms. For usage, see Improve recognition accuracy.

ImportantThe context parameter is supported only by the fun-asr-realtime models.

The dict must include a context key whose value is a list of messages (list[dict]). Each message contains the following fields:

  • role (str, required): The message role. user represents the recognition results from previous user turns or a domain-specific word list. assistant represents the large language model responses from previous turns.
  • content (list[dict], required): The list of message content. Each element contains type (str; set to input_text when role is user, and text when role is assistant) and text (str, the text content).

ImportantContext 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.

ImportantWhen 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).

NoteThis field requires SDK version 2.0.1 or later.

# Build the input to pass in
input_context = {
    "context": [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Hello there"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "Hello, I am Qwen. How can I help you?"
                }
            ]
        }
    ]
}

# Pass it in through the input parameter when creating the recognition session
recognition = client.audio.asr.recognize(
    model='fun-asr-realtime',
    format='wav',
    sample_rate=16000,
    input=input_context,
)

API reference

Qwen-Audio-ASR-Streaming / Fun-ASR-Realtime

Sentence information (Sentence)

The members of the Sentence class are as follows:

ParameterTypeDescription
begin_timeintSentence start time, in ms.
end_timeintSentence end time, in ms.
textstrRecognized text.
wordsA 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:

ParameterTypeDescription
begin_timeintWord start time, in ms.
end_timeintWord end time, in ms.
textstrThe word.
punctuationstrThe 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 methodMethod signatureDescription

recognize

def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition
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

def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]
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
def start(self)
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
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 event iteration (events()/results()).

stop
def stop(self)
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

def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]
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

def close(self)
Closes the recognition session. Called automatically when exiting the with context.

request_id / first_package_delay / last_package_delay / last_response

rec.request_id
rec.first_package_delay
rec.last_package_delay
rec.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.

# Iterate raw events: recognition text is in payload.output.sentence
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('Recognized text:', sentence['text'])


# Or iterate recognition result frames only (returns RecognitionResult, heartbeat frames filtered out)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('Recognized text:', sentence['text'])
Event/iteration methodOutputReturn valueDescription
event["header"]["event"] == "task-started"

task-started event

NoneRead internally by start() and saved in last_response when it returns; not yielded again by events().
def events(self) -> Iterator[Dict]
event: server event dictIteratorYields 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.
def results(self) -> Iterator[RecognitionResult]
result: recognition result (RecognitionResult)IteratorYields only recognition result frames (heartbeat frames filtered out); the iteration ends after all recognition results are returned.
try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
DashScopeError exceptionNoneRaised in the sending/receiving thread when an error occurs; catch it with try/except.
event["header"]["event"] == "task-finished"

task-finished event

NoneYielded 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 methodMethod signatureDescription
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]
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
result.request_id
The request_id of the current event.
is_sentence_end
def is_sentence_end(self) -> bool
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 methodMethod signatureDescription

recognize

def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition

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

def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]

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

def start(self)

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

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 event iteration (events()/results()).

stop

def stop(self)

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

def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]

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

def close(self)

Closes the recognition session. Called automatically when the with context is exited.

request_id / first_package_delay / last_package_delay / last_response

rec.request_id
rec.first_package_delay
rec.last_package_delay
rec.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

Call update_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.

def update_context(self, context: dict)
  • When to call: After entering the with context (which automatically calls start) to start streaming recognition, and before calling stop.
  • Parameter: context is a dictionary containing the payload.input object of a continue-task event, including the context field. Do not add an extra payload or input wrapper.
  • Supported models and parameter constraints: See continue-task.

The following example uses an existing, started recognition instance.

payload_input = {
    "context": [
        {
            "role": "user",
            "content": [{"type": "input_text", "text": "Hello"}]
        },
        {
            "role": "assistant",
            "content": [{"type": "text", "text": "Hello, I am Qwen. How can I help you?"}]
        }
    ]
}
recognition.update_context(context=payload_input)
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.

# Iterate raw events: the recognized text is in payload.output.sentence
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('Recognized text: ', sentence['text'])


# Or iterate only recognition result frames (returns RecognitionResult, heartbeat frames are filtered out)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('Recognized text: ', sentence['text'])
Event/iteration methodOutputReturn valueDescription
event["header"]["event"] == "task-started"

task-started event

None

Read internally by start() and stored in last_response when it returns; it is not yielded again by events().

def events(self) -> Iterator[Dict]

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.

def results(self) -> Iterator[RecognitionResult]

result: recognition result (RecognitionResult)

Iterator

Yields only recognition result frames (heartbeat frames are filtered out), and iteration ends after all recognition results are returned.

try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)

DashScopeError exception

None

Raised in the sending/receiving thread when an error occurs; catch it with try/except.

event["header"]["event"] == "task-finished"

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 methodMethod signatureDescription
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]

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
result.request_id
The request_id of the current event.
is_sentence_end
def is_sentence_end(self) -> bool
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:

ParameterTypeDescription
begin_timeintSentence start time, in ms.
end_timeintSentence end time, in ms.
textstrRecognized text.
wordsA 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:

ParameterTypeDescription
begin_timeintWord start time, in ms.
end_timeintWord end time, in ms.
textstrThe word.
punctuationstrThe 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 methodMethod signatureDescription

recognize

def recognize(self,
              *,
              model: str,
              format: str = "pcm",
              sample_rate: int = 16000,
              vocabulary_id: str = None,
              disfluency_removal_enabled: bool = None,
              diarization_enabled: bool = None,
              parameters: Dict = None,
              input: Dict = None,
              phrase_id: str = None,
              ...) -> Recognition
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

def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]
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

def start(self)
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

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 by iterating events()/results().

stop

def stop(self)
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

def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]
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

def close(self)
Closes the recognition session. Automatically called when exiting the with context.

request_id / first_package_delay / last_package_delay / last_response

rec.request_id
rec.first_package_delay
rec.last_package_delay
rec.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.

# Iterate raw events: the recognition text is in payload.output.sentence
def receive_events(rec):
    for event in rec.events():
        payload = event.get('payload') or {}
        sentence = (payload.get('output') or {}).get('sentence') or {}
        if sentence.get('text') and not sentence.get('heartbeat'):
            print('Recognized text: ', sentence['text'])


# Or iterate only recognition result frames (returns RecognitionResult, heartbeat frames filtered out)
def receive_results(rec):
    for result in rec.results():
        sentence = result.get_sentence()
        if sentence and 'text' in sentence:
            print('Recognized text: ', sentence['text'])
Event/iteration methodOutputReturn valueDescription
event["header"]["event"] == "task-started"
task-started eventNoneRead internally by start() and saved in last_response when the start returns. It is not yielded again by events().
def events(self) -> Iterator[Dict]
event: server event dictIteratorYields 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.
def results(self) -> Iterator[RecognitionResult]
result: recognition result (RecognitionResult)IteratorYields only recognition result frames (heartbeat frames are filtered out). The iteration ends after all recognition results are returned.
try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
DashScopeError exceptionNoneRaised in the sending/receiving thread when an error occurs. You can catch it with try/except.
event["header"]["event"] == "task-finished"
task-finished eventNoneYielded 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 methodMethod signatureDescription
get_sentence
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]
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
result.request_id
The request_id corresponding to the current event.
is_sentence_end
def is_sentence_end(self) -> bool
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.

Error codes

If you encounter errors, see Error codes for troubleshooting.

If the issue persists, join the developer community listed in the speech SDK sample repository to report your issue and provide the Request ID for further investigation.