Skip to main content
QwenCloud home page
Docs
Non-realtime

Qwen-Audio-3.0-ASR-Flash-Filetrans/Fun-ASR recording Python SDK

File transcription Python

This topic describes the parameters and interfaces of the Qwen-Audio-3.0-ASR-Flash-Filetrans/Fun-ASR non-real-time speech recognition Python SDK. User guide: Non-real-time speech recognition. For input requirements such as supported audio formats, file size limits, and duration limits, see Audio specifications.

Prerequisites

For temporary access to third-party apps, use a temporary token. Tokens expire in 60 seconds, limiting leakage risk.

Model availability

ModelVersionUnit priceFree quota (Note)
fun-asr
Currently, fun-asr-2025-11-07		Stable$0.000035/second36,000 seconds (10 hours)
Valid for 90 days
fun-asr-2025-11-07
Improved far-field VAD over fun-asr-2025-08-25 for higher accuracy		Snapshot$0.000035/second36,000 seconds (10 hours)
Valid for 90 days
fun-asr-2025-08-25Snapshot$0.000035/second36,000 seconds (10 hours)
Valid for 90 days
fun-asr-mtl
Currently, fun-asr-mtl-2025-08-25		Stable$0.000035/second36,000 seconds (10 hours)
Valid for 90 days
fun-asr-mtl-2025-08-25Snapshot$0.000035/second36,000 seconds (10 hours)
Valid for 90 days
  • Supported languages:
    • fun-asr, fun-asr-2025-11-07, fun-asr-mtl, and fun-asr-mtl-2025-08-25: Chinese (Mandarin, Cantonese, Wu, Minnan, Hakka, Gan, Xiang, and Jin; also supports Mandarin accents from Zhongyuan, Southwest, Jilu, Jianghuai, Lanyin, Jiaoliao, Northeast, Beijing, and Hong Kong-Taiwan regions -- including Henan, Shaanxi, Hubei, Sichuan, Chongqing, Yunnan, Guizhou, Guangdong, Guangxi, Hebei, Tianjin, Shandong, Anhui, Nanjing, Jiangsu, Hangzhou, Gansu, and Ningxia), English, Japanese, Korean, Vietnamese, Indonesian, Thai, Malay, Filipino, Arabic, Bulgarian, Croatian, Czech, Danish, Dutch, Estonian, Finnish, Greek, Hindi, Hungarian, Irish, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Slovak, Slovenian, and Swedish.
    • fun-asr-2025-08-25: Mandarin and English.
  • Sample rates supported: Any
  • Audio formats supported: aac, amr, avi, flac, flv, m4a, mkv, mov, mp3, mp4, mpeg, ogg, opus, wav, webm, wma, wmv

Limitations

Files must be at public URLs (HTTP/HTTPS, such as https://your-domain.com/file.mp3). Local files and Base64 encoding are not supported. Pass URLs with the file_urls parameter. Up to 100 URLs per request.
  • Audio formats: aac, amr, avi, flac, flv, m4a, mkv, mov, mp3, mp4, mpeg, ogg, opus, wav, webm, wma, wmv
Not all format variants are tested. Test your files to verify results.
  • Audio sample rate: Any
  • File size and duration: Max 2 GB and 12 hours. For larger files, see Audio trimming.
  • Batch processing: Up to 100 URLs per request.
  • Languages: fun-asr, fun-asr-mtl, and their snapshot versions support Chinese and 29 other languages. fun-asr-2025-08-25 supports Chinese and English only. See Supported languages.

Request parameters

Set request parameters through the async_call method of the Transcription class.
ParameterTypeRequiredDescription
modelstrYesThe model name. Supported values include the Qwen-Audio-3.0-ASR-Flash-Filetrans and Fun-ASR model families. For details, see Supported models.
file_urlslist[str]YesA list of URLs of the audio or video files to transcribe. HTTP and HTTPS are supported. A single request supports only one URL. For input requirements such as supported audio formats, file size limits, and duration limits, see Audio specifications. If the recording is stored in Alibaba Cloud OSS, the RESTful API supports temporary URLs prefixed with oss://, whereas the SDK does not support oss://-prefixed temporary URLs.
A temporary URL is valid for 48 hours and cannot be used after it expires. Do not use it in production. The upload credential interface is rate-limited to 100 QPS and cannot be scaled up. Do not use it in production, high-concurrency, or load-testing scenarios. For production, use stable storage such as Alibaba Cloud OSS to keep files available long-term and avoid rate limiting.
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 configured together with precompiled hot words, only the instant hot words take effect. For usage details, see Instant hotwords.
Only qwen-audio-3.0-asr-flash-filetrans supports inline hotwords.
channel_idlist[int]NoThe index of the audio tracks to recognize in a multi-track audio file. The index starts at 0. For example, [0] recognizes the first track, and [0, 1] recognizes the first and second tracks at the same time. If you omit this parameter, only the first track is processed. Default value: [0].
Each specified track is billed independently. For example, requesting [0, 1] for a single file incurs two separate charges.
special_word_filterstrNoThe sensitive words to process during speech recognition. You can set a different handling method for each sensitive word. For details, see Sensitive word filtering.
diarization_enabledboolNoWhether to enable speaker diarization. Disabled by default. Applies only to mono audio. Multi-channel audio does not support speaker diarization. When enabled, the recognition result includes a speaker_id field that distinguishes different speakers.
When speaker diarization is enabled, keep the audio duration within 2 hours. Otherwise, recognition may fail or time out.
Default value: False. For an example of speaker_id, see Recognition result.
speaker_countintNo
Takes effect only when speaker diarization is enabled (diarization_enabled is set to True).
A reference value for the number of speakers. The valid range is an integer from 2 to 100 (inclusive). By default, the number of speakers is detected automatically. If you set this value, it only guides the algorithm to output the specified count when possible and does not guarantee that exact count. No default value.
language_hintslist[str]NoThe language codes to recognize. If you cannot determine the language in advance, leave it unset and the model detects the language automatically. For Qwen-Audio-3.0-ASR-Flash-Filetrans models, you can set up to 4 values; any values beyond the first 4 are ignored. For Fun-ASR models, you can set only 1 value; if you set multiple, only the first takes effect. See Supported languages.
speech_noise_thresholdfloatNoSpeech noise threshold.

Vocabulary example

from dashscope.audio.asr import Transcription
vocab = {"Zhang San": 5, "Li Si": 5}
result = Transcription.async_call(
  model="qwen-audio-3.0-asr-flash-filetrans",
  vocabulary=vocab,
  file_urls=['{YOUR_AUDIO_URL}']
)

Sensitive word filter

By default, words on the QwenCloud sensitive word list are replaced with asterisks (*). With special_word_filter, you can:
  • Replace with *: Matched words become asterisks.
  • Filter out: Matched words are removed.
Value must be a JSON string: 
{
  "filter_with_signed": {
    "word_list": ["test"]
  },
  "filter_with_empty": {
    "word_list": ["start", "happen"]
  },
  "system_reserved_filter": true
}
Fields:
  • filter_with_signed (object, optional): Words to replace with *.
    • Example: "Help me test this code" becomes "Help me **** this code"
    • word_list: Words to replace.
  • filter_with_empty (object, optional): Words to remove.
    • Example: "Is the game about to start?" becomes "Is the game about to?"
    • word_list: Words to remove.
  • system_reserved_filter (boolean, optional, default: true): Enable system filtering. When true, words on the QwenCloud sensitive word list are replaced with *.

Supported languages

Language codes by model:
  • qwen-audio-3.0-asr-flash-filetrans, fun-asr, fun-asr-2025-11-07, fun-asr-mtl, fun-asr-mtl-2025-08-25:
    • zh: Chinese
    • en: English
    • ja: Japanese
    • ko: Korean
    • vi: Vietnamese
    • id: Indonesian
    • th: Thai
    • ms: Malay
    • tl: Filipino
    • ar: Arabic
    • bg: Bulgarian
    • hr: Croatian
    • cs: Czech
    • da: Danish
    • nl: Dutch
    • et: Estonian
    • fi: Finnish
    • el: Greek
    • hi: Hindi
    • hu: Hungarian
    • ga: Irish
    • lv: Latvian
    • lt: Lithuanian
    • mt: Maltese
    • pl: Polish
    • pt: Portuguese
    • ro: Romanian
    • sk: Slovak
    • sl: Slovenian
    • sv: Swedish
  • fun-asr-2025-08-25:
    • zh: Chinese
    • en: English

Response

TranscriptionResponse

TranscriptionResponse wraps the basic task information (task_id and task_status) and the task result (the content of the output attribute, see TranscriptionOutput).
  • PENDING status
  • RUNNING status
  • SUCCEEDED status
  • FAILED status
{
  "status_code": 200,
  "request_id": "251aceab-a6aa-9fc4-b7f7-0cc6d3e2a9f3",
  "code": null,
  "message": "",
  "output": {
    "task_id": "7d0a58a3-1dbe-4de9-8cff-5f48213128b0",
    "task_status": "PENDING",
    "submit_time": "2025-02-13 16:55:08.573",
    "scheduled_time": "2025-02-13 16:55:08.592",
    "task_metrics": {
      "TOTAL": 2,
      "SUCCEEDED": 0,
      "FAILED": 0
    }
  },
  "usage": null
}
Key parameters:
ParameterDescription
status_codeHTTP status code of the request.
codeThe outermost code can be ignored. The code under output.results is the error code. Combine it with the message field and refer to Error codes to troubleshoot the issue.
messageThe outermost message can be ignored. The message under output.results is the error message. Combine it with the code field and refer to Error codes to troubleshoot the issue.
task_idTask ID.
task_statusTask status. One of four states: PENDING, RUNNING, SUCCEEDED, and FAILED. When a task contains multiple subtasks, the overall task status is marked as SUCCEEDED as long as any subtask succeeds. Check the subtask_status field to determine the result of each subtask.
resultsSubtask recognition results.
subtask_statusSubtask status. One of four states: PENDING, RUNNING, SUCCEEDED, FAILED.
file_urlURL of the recognized audio.
transcription_urlURL of the audio recognition result. The recognition result is saved as a JSON file. You can download the file from the link associated with transcription_url or read its content directly through an HTTP request. For the contents of the JSON file, see Recognition result.

TranscriptionOutput

TranscriptionOutput corresponds to the output attribute of the TranscriptionResponse and represents the result of the current task.
  • PENDING status
  • RUNNING status
  • SUCCEEDED status
  • FAILED status
{
  "task_id": "f2f7c2fa-0cd9-4bb2-a283-27b26ee4bb67",
  "task_status": "PENDING",
  "submit_time": "2025-02-13 17:59:27.754",
  "scheduled_time": "2025-02-13 17:59:27.789",
  "task_metrics": {
    "TOTAL": 2,
    "SUCCEEDED": 0,
    "FAILED": 0
  }
}
Key parameters:
ParameterDescription
codeThe error code. Combine it with the message field and refer to Error codes to troubleshoot the issue.
messageThe error message. Combine it with the code field and refer to Error codes to troubleshoot the issue.
task_idTask ID.
task_statusTask status. One of four states: PENDING, RUNNING, SUCCEEDED, and FAILED. When a task contains multiple subtasks, the overall task status is marked as SUCCEEDED as long as any subtask succeeds. Check the subtask_status field to determine the result of each subtask.
resultsSubtask recognition results.
subtask_statusSubtask status. One of four states: PENDING, RUNNING, SUCCEEDED, FAILED.
file_urlURL of the recognized audio.
transcription_urlURL of the audio recognition result. The recognition result is saved as a JSON file. You can download the file from the link associated with transcription_url or read its content directly through an HTTP request. For the contents of the JSON file, see Recognition result.

Recognition result

The recognition result is saved as a JSON file. 
{
  "file_url": "{YOUR_AUDIO_URL}",
  "properties": {
    "audio_format": "pcm_s16le",
    "channels": [
      0
    ],
    "original_sampling_rate": 16000,
    "original_duration_in_milliseconds": 3834
  },
  "transcripts": [
    {
      "channel_id": 0,
      "content_duration_in_milliseconds": 3720,
      "text": "Hello world, this is Alibaba Speech Lab.",
      "sentences": [
        {
          "begin_time": 100,
          "end_time": 3820,
          "text": "Hello world, this is Alibaba Speech Lab.",
          "sentence_id": 1,
          "speaker_id": 0,
          "words": [
            {
              "begin_time": 100,
              "end_time": 596,
              "text": "Hello ",
              "punctuation": ""
            },
            {
              "begin_time": 596,
              "end_time": 844,
              "text": "world",
              "punctuation": ", "
            }
          ]
        }
      ]
    }
  ]
}
speaker_id appears only when speaker diarization is enabled.
The following parameters are worth noting:
ParameterTypeDescription
audio_formatstringThe audio format of the source file.
channelsarray[integer]The track index of the audio in the source file. For single-track audio, [0] is returned; for dual-track audio, [0, 1] is returned; and so on.
original_sampling_rateintegerThe sampling rate (Hz) of the audio in the source file.
original_duration_in_millisecondsintegerThe original audio duration (ms) in the source file.
channel_idintegerThe track index of the transcription result, starting from 0.
content_durationintegerThe duration (ms) of content in the track that is identified as speech.
The speech recognition model service transcribes only the content in a track that is identified as speech, and meters and bills based on that duration. Non-speech content is not metered or billed. Typically, the speech content duration is shorter than the original audio duration. Because whether speech content exists is determined by an AI model, the result may differ slightly from the actual situation.
transcriptstringThe paragraph-level transcription result.
sentencesarrayThe sentence-level transcription result.
wordsarrayThe word-level transcription result.
begin_timeintegerThe start timestamp (ms).
end_timeintegerThe end timestamp (ms).
textstringThe transcription result.
speaker_idintegerThe index of the current speaker, starting from 0, used to distinguish between different speakers. This field appears in the recognition result only when speaker diarization is enabled.
punctuationstringThe punctuation predicted after the word, if any.

Transcription class

Import Transcription with from dashscope.audio.asr import Transcription.
MethodSignatureDescription
async_call@classmethod def async_call(cls, model: str, file_urls: List[str], phrase_id: str = None, api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponseSubmits a speech recognition task asynchronously.
wait@classmethod def wait(cls, task: Union[str, TranscriptionResponse], api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponseBlocks the current thread until the asynchronous task finishes (the task status is SUCCEEDED or FAILED). This method returns a TranscriptionResponse.
fetch@classmethod def fetch(cls, task: Union[str, TranscriptionResponse], api_key: str = None, workspace: str = None, **kwargs) -> TranscriptionResponseQueries the result of the current task asynchronously. This method returns a TranscriptionResponse.

Error codes

If you encounter an error, see Error codes to troubleshoot. When a task contains multiple subtasks, the overall task status is marked as SUCCEEDED as long as at least one subtask succeeds. Check the subtask_status field to determine the result of each subtask. Error response example: 
{
  "task_id": "7bac899c-06ec-4a79-8875-xxxxxxxxxxxx",
  "task_status": "SUCCEEDED",
  "submit_time": "2024-12-16 16:30:59.170",
  "scheduled_time": "2024-12-16 16:30:59.204",
  "end_time": "2024-12-16 16:31:02.375",
  "results": [
    {
      "file_url": "{YOUR_AUDIO_URL}",
      "code": "InvalidFile.DownloadFailed",
      "message": "The audio file cannot be downloaded.",
      "subtask_status": "FAILED"
    }
  ],
  "task_metrics": {
    "TOTAL": 1,
    "SUCCEEDED": 0,
    "FAILED": 1
  }
}

FAQ

Features

Q: Is Base64-encoded audio supported? Base64-encoded audio is not supported. Only audio at a publicly accessible URL can be recognized. Binary streams and local files cannot be recognized directly. Q: How do I make an audio file available at a publicly accessible URL? The typical steps are as follows. This is one approach; the exact process varies by storage product. We recommend that you upload the audio to Alibaba Cloud OSS:
For example:
  • Object storage service (recommended):
    • Use a cloud provider's object storage service (such as Alibaba Cloud OSS) to upload the audio file to a bucket and set it to public access.
    • Advantages: high availability, CDN acceleration support, and easy management.
  • Web server:
    • Place the audio file on a web server that supports HTTP/HTTPS access (such as Nginx or Apache).
    • Advantages: suitable for small projects or local testing.
  • Content delivery network (CDN):
    • Host the audio file on a CDN and access it through the URL that the CDN provides.
    • Advantages: accelerates file delivery and suits high-concurrency scenarios.
Upload the audio according to the storage or hosting method you chose. For example:
  • Object storage service:
    • Log in to the cloud provider's console and create a bucket.
    • Upload the audio file, and set its permission to public read or generate a temporary access link.
  • Web server:
    • Place the audio file in a designated directory on the server (such as /var/www/html/audio/).
    • Make sure the file is accessible over HTTP/HTTPS.
For example:
  • Object storage service:
    • After the file is uploaded, the system automatically generates a public access URL (typically in the format https://<bucket-name>.<region>.aliyuncs.com/<file-name>).
    • For a friendlier domain name, bind a custom domain and enable HTTPS.
  • Web server:
    • The access URL is usually the server address plus the file path (such as https://your-domain.com/audio/file.mp3).
  • CDN:
    • After you configure CDN acceleration, use the URL that the CDN provides (such as https://cdn.your-domain.com/audio/file.mp3).
Make sure the generated URL is accessible over the public network. For example:
  • Open the URL in a browser and check whether the audio file plays.
  • Use a tool (such as curl or Postman) to verify that the URL returns the correct HTTP response (status code 200).
When using the SDK, if audio files are stored in Alibaba Cloud OSS, temporary URLs with the oss:// prefix are not supported.When using the RESTful API, if audio files are stored in Alibaba Cloud OSS, temporary URLs with the oss:// prefix are supported:
  • The temporary URL is valid for 48 hours and cannot be used after it expires. Do not use it in a production environment.
  • The API for obtaining an upload credential is limited to 100 QPS and does not support scaling out. Do not use it in production environments, high-concurrency scenarios, or stress testing scenarios.
  • For production environments, use a stable storage service such as OSS to ensure long-term file availability and avoid rate limiting issues.
Q: How long does it take to get the recognition result? After a task is submitted, it enters the queued (PENDING) state. The queuing time depends on the queue length and the audio duration, so it cannot be stated exactly, but it is usually within a few minutes. In general, the longer the audio, the longer it takes.

Troubleshooting

If you encounter a code error, troubleshoot the issue based on the information in Error codes. Q: Polling never returns a result? This may be caused by throttling. Wait a moment and try again. Q: Why can't the speech be recognized (no recognition result)? Check that the audio format and sample rate are correct and meet the parameter constraints. Use the ffprobe tool to get the audio container, codec, sample rate, channels, and other details: 
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx