Skip to main content
SDK access

Fun-ASR-Realtime Python SDK

This topic describes the parameters and interfaces of the Python SDK for the Fun-ASR-Realtime real-time speech recognition model.

Prerequisites

Quick start

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
  • Bidirectional 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 request parameters, pass in the local file path, and iterate server events to obtain the recognition result.
import os
import dashscope

# If you have not configured the environment variable, replace the following line with your QwenCloud API Key: api_key="sk-xxx"
client = dashscope.Client(api_key=os.environ.get('DASHSCOPE_API_KEY'))

# 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='fun-asr-realtime',
        format='wav',
        sample_rate=16000,
        # Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
        # API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
        ws_url='wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/inference'):
    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'])

Request parameters

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
Tip: opus/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_enabledboolNoWhether 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.
  • 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 (China North 2 (Beijing) only):
  • zh: Chinese
  • en: English
  • ja: Japanese
  • fun-asr-flash-8k-realtime, fun-asr-flash-8k-realtime-2026-01-28 (China North 2 (Beijing) only):
  • 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 Quick start. Tip: The 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).
Tip: 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. Tip: 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). Note: This field requires SDK version 2.0.1 or later. See Example 1 below
Example 1 (Description):
# 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,
)

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
recognizeSee Example 1 belowCreates 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_fileSee Example 2 belowA 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.
startSee Example 3 belowStarts 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_frameSee Example 4 belowPushes 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().
stopSee Example 5 belowStops 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 / resultsSee Example 6 belowIterates 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).
closeSee Example 7 belowCloses the recognition session. Called automatically when exiting the with context.
request_id / first_package_delay / last_package_delay / last_responseSee Example 8 belowGets 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.
Example 1 (Method signature):
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
Example 2 (Method signature):
def recognize_file(self,
                   path: str,
                   *,
                   model: str,
                   format: str = "pcm",
                   sample_rate: int = 16000,
                   ...) -> Iterator[Dict]
Example 3 (Method signature):
def start(self)
Example 4 (Method signature):
def send_audio_frame(self, buffer: bytes)
Example 5 (Method signature):
def stop(self)
Example 6 (Method signature):
def events(self) -> Iterator[Dict]
def results(self) -> Iterator[RecognitionResult]
Example 7 (Method signature):
def close(self)
Example 8 (Method signature):
rec.request_id
rec.first_package_delay
rec.last_package_delay
rec.last_response

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 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
See Example 1 belowtask-started eventNoneRead internally by start() and saved in last_response when it returns; not yielded again by events().
See Example 2 belowevent: 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.
See Example 3 belowresult: Recognition result (RecognitionResult)IteratorYields only recognition result frames (heartbeat frames filtered out); the iteration ends after all recognition results are returned.
See Example 4 belowDashScopeError exceptionNoneRaised in the sending/receiving thread when an error occurs; catch it with try/except.
See Example 5 belowtask-finished eventNoneYielded by events() after the server completes all recognition; the iteration then ends. You must still read this event after calling stop().
Example 1 (Event):
event["header"]["event"] == "task-started"
Example 2 (Event):
def events(self) -> Iterator[Dict]
Example 3 (Event):
def results(self) -> Iterator[RecognitionResult]
Example 4 (Event):
try:
    ...
except DashScopeError as e:
    print(e.code, e.message, e.request_id)
Example 5 (Event):
event["header"]["event"] == "task-finished"

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).
ParameterTypeDescription
get_sentenceSee Example 1 belowGets the current recognized sentence and its timestamp information. This method returns Dict[str, Any] (single-sentence information). For details, see Sentence (Sentence).
request_idSee Example 2 belowThe request_id of the current event.
is_sentence_endSee Example 3 belowDetermines 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.
Example 1 (Method signature):
def get_sentence(self) -> Union[Dict[str, Any], List[Any]]
Example 2 (Method signature):
result.request_id
Example 3 (Method signature):
def is_sentence_end(self) -> bool

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.

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.

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.
# Basic conversion command (all-purpose template)
# -i, purpose: input file path, example value: audio.wav
# -c:a, purpose: audio codec, example values: aac, libmp3lame, pcm_s16le
# -b:a, purpose: bitrate (audio quality control), example values: 192k, 320k
# -ar, purpose: sample rate, example values: 44100 (CD), 48000, 16000
# -ac, purpose: number of channels, example values: 1 (mono), 2 (stereo)
# -y, purpose: overwrite an existing file (no value needed)
ffmpeg -i input_audio.ext -c:a codec_name -b:a bitrate -ar sample_rate -ac channels output.ext

# For example: WAV to MP3 (keep the original quality)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# For example: MP3 to WAV (16-bit PCM standard format)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# For example: M4A to AAC (extract or convert Apple audio)
ffmpeg -i input.m4a -c:a copy output.aac  # Extract directly without re-encoding
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac  # Re-encode to improve quality
# For example: FLAC lossless to Opus (high compression)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opus

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 call the recognize_file method to pass the file path and 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_frame method of the recognition session.

Troubleshooting

Q: Why can't the speech be recognized (no recognition result)?

  1. 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 format request parameter is set to mp3 (incorrect parameter setting).
    • The audio sample rate is 3600 Hz, but the sampleRate/sample_rate request parameter is set to 48000 (incorrect parameter setting).
    Use the ffprobe tool to get the container, codec, sample rate, channels, and other information of the audio:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx
  1. If none of the checks above reveal a problem, add custom hotwords to improve recognition of specific terms.