Qwen-Audio-3.0-ASR-Flash-Filetrans/Fun-ASR HTTP API for non-real-time speech recognition

User guide:Non-real-time speech recognition. For input requirements such as supported audio formats, file size limits, and duration limits, see Audio specifications.

How it works

Unlike synchronous DashScope calls, which return the result immediately in a single request, asynchronous calls are designed for long audio files or time-consuming tasks. This mode uses a two-step submit-and-poll flow that avoids request timeouts caused by long waits:

Step 1: Submit the task.
- The client sends an asynchronous processing request.
- After validating the request, the server does not run the task immediately. Instead, it returns a unique task_id to indicate that the task was created successfully.
Step 2: Retrieve the result.
- The client uses the returned task_id to poll the query interface repeatedly.
- When the task finishes, the query interface returns the final recognition result.

Service endpoints

Singapore
China (Beijing)

Submit task interface: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcriptionQuery task interface: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}Replace {WorkspaceId} with your actual Workspace ID.

Alibaba 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

Replace {WorkspaceId} with your actual Workspace ID. The existing domains remain fully functional.

When you submit a task with the new domain (https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com), the request body must include the parameters object. Even if you don't need to set any parameters, pass an empty object {}. Otherwise, the task is submitted successfully but recognition fails.

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	Authentication token in the format `Bearer <your_api_key>`. Replace "`<your_api_key>`" with your actual API key. Required for both the submit task interface and the query task interface.
Content-Type	string	Yes	The media type of the request body. Required only for the submit task interface. Fixed value: `application/json`.
X-DashScope-Async	string	Yes	The asynchronous task flag. Required only for the submit task interface. Fixed value: `enable`. Do not omit it, or the task cannot be submitted.

Submit task interface

Submits a speech recognition task. This interface returns asynchronously, so poll the task status with the Query task interface.

Request body

modelstring(Required)The model name. Supported values include the Qwen-Audio-3.0-ASR-Flash-Filetrans and Fun-ASR model families. For details, see Supported models and regions.inputobject(Required)The input parameter object.

Properties

file_urls array[string](Required)A 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.
If an audio file URL set to an OSS temporary public URL is unreachable, set X-DashScope-OssResourceResolve to enable in the request header (not recommended). The SDK does not support configuring request headers.

contextarray(object)(Optional)A list of messages that provide optional conversation context to improve recognition accuracy.

The SDK does not yet support this feature.

Context enhancement improves the recognition accuracy of domain-specific terms. For usage, see Context enhancement.Constraints: Context messages of the input_text and text types are each limited to 5 messages. If you exceed this limit, only the most recent 5 are kept. The total text length per context turn (the combined length of the text fields for user and assistant) must not exceed 400 characters (counted per character, each character counts as 1). Any excess is truncated from the end.

When you include context, the message order in messages matters: context messages must be arranged by conversation turn. Within each turn, the user message (input_text type) must come before the corresponding assistant message (text type). A user message that contains input_audio must be placed last in the messages array.

Properties

rolestring(Required)The message role. Valid values:

user: recognition results from previous turns or a domain-specific word list.
assistant: the large language model's replies from previous turns.

contentarray(object)(Required)The list of message content items.

Properties

typestring(Required)The content type. Valid values:

input_text (optional, context): recognition results of the user's speech from previous turns, or a domain-specific word list (role is user). You must also pass the text field.
text (optional, context): the large language model's replies from previous turns (role is assistant). You must also pass the text field.

textstring(Conditionally required)When type is input_text, enter the recognition results of the user's speech from previous turns or a domain-specific word list. When type is text, enter the large language model's replies from previous turns. Text is counted per character, and each character counts as 1. The combined length of the text fields across all messages in a context turn must not exceed 400 characters. Any excess is truncated from the end.

parametersobject(Optional)The request parameter object.

When you use the new domain (https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com), parameters is required. Even if you don't need to set any parameters, pass an empty object {}. If you omit this field, the task is submitted successfully, but the query task interface returns a recognition failure.

Properties

vocabulary_id string(Optional)The ID of a precompiled hot word list.Generate this ID in advance by calling the create hot word list API. Pass the ID during recognition to use the hot words in the list.Suitable for scenarios where the vocabulary is known and relatively stable, and where you need to reuse the same word list across requests.For usage details, see Precompiled hotwords.vocabulary object(Optional)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.

Only qwen-audio-3.0-asr-flash-filetrans supports inline hotwords.

channel_id array[integer](Optional)The 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.

Each specified track is billed independently. For example, requesting [0, 1] for a single file incurs two separate charges.

Default value: [0].special_word_filter string(Optional)The 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_enabled boolean(Optional)Whether 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.

For an example of speaker_id, see Recognition result description.Default value: false.speaker_count integer(Optional)

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_hints array[string](Optional)The language codes to recognize. If you can't 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.

Click to view the supported language codes

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
- 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-2025-08-25:
- zh: Chinese
- en: English

Basic call
Inline hotwords
Context

The following example uses the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region. The Singapore region and the Beijing region use different API keys.

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-Async: enable" \
     --data '{
    "model": "qwen-audio-3.0-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "channel_id": [0]
    }
}'

Use inline hotwords in the following format:

{
    "model": "qwen-audio-3.0-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ]
    },
    "parameters": {
        "vocabulary": {"John Smith": 5, "Jane Doe": 5}
    }
}

Use context in the following format:

{
    "model": "qwen-audio-3.0-asr-flash-filetrans",
    "input": {
        "file_urls": [
            "{YOUR_AUDIO_URL}"
        ],
        "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?"
                    }
                ]
            }
        ]
    },
    "parameters": {
        "vocabulary": {"John Smith": 5, "Jane Doe": 5}
    }
}

Response body

request_idstringThe unique identifier of this call.outputobjectThe data returned by the submit task interface.

Properties

task_idstringThe task ID. Pass this ID as the string in the Query task interface.task_statusstringThe task status. Returns PENDING on successful submission.

{
  "output": {
    "task_status": "PENDING",
    "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942--************"
}

Query task interface

Queries the execution status and result of a speech recognition task. Poll this interface until the task reaches a terminal state.

Request body

task_idstring(Required)

This parameter is a URL path parameter. There is no request body.

To query a task, specify its ID. This ID is the task_id returned when the Submit task interface is called.

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response body

request_idstringThe unique identifier of this call.outputobjectThe data returned by the query task interface.

Properties

task_idstringThe ID of the queried task.task_statusstringThe status of the queried task.

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 a specific subtask.

submit_timestringThe time the task was submitted.scheduled_timestringThe time the task was scheduled to run.end_timestringThe time the task ended.resultsarray[object]The list of subtask results, one for each audio file to recognize.

Properties

subtask_statusstringThe subtask status.file_urlstringThe URL of the file processed by the file transcription task.transcription_urlstringThe link to the recognition result. This link is valid for 24 hours. After it expires, you cannot query the task or download the result through the URL returned by a previous query.The recognition result is saved as a JSON file. You can download the file through the link above or read its content directly with an HTTP request. For the meaning of each field in the JSON data, see Recognition result description.codestring

Returned only when the subtask fails.

The error code of the failed subtask.messagestring

Returned only when the subtask fails.

The error message of the failed subtask.

task_metricsobjectOverall execution statistics for the task.

Properties

TOTALintegerThe total number of subtasks.SUCCEEDEDintegerThe number of successful subtasks.FAILEDintegerThe number of failed subtasks.

{
  "request_id": "f9e1afad-94d3-997e-a83b-************",
  "output": {
    "task_id": "f86ec806-4d73-485f-a24f-************",
    "task_status": "SUCCEEDED",
    "submit_time": "2024-09-12 15:11:40.041",
    "scheduled_time": "2024-09-12 15:11:40.071",
    "end_time": "2024-09-12 15:11:40.903",
    "results": [
      {
        "file_url": "{YOUR_AUDIO_URL}",
        "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/409a4b92-445b-4dd8-8c1d-f110954d82d8-1.json?Expires=1726211500&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
        "subtask_status": "SUCCEEDED"
      }
    ],
    "task_metrics": {
      "TOTAL": 1,
      "SUCCEEDED": 1,
      "FAILED": 0
    }
  },
  "usage": {
    "duration": 9
  }
}

Other interfaces: batch-query task status / cancel a task

For details, see Manage asynchronous tasks: you can batch-query non-real-time speech recognition tasks submitted within the last 24 hours, and cancel tasks in the PENDING (queued) state.

Recognition result description

The recognition result is saved as a JSON file.

Click to view the recognition result example

{
    "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, //This field is displayed only when automatic speaker diarization is enabled
                    "words":[
                        {
                            "begin_time":100,
                            "end_time":596,
                            "text":"Hello ",
                            "punctuation":""
                        },
                        {
                            "begin_time":596,
                            "end_time":844,
                            "text":"world",
                            "punctuation":", "
                        }
                        // Other content is omitted here
                    ]
                }
            ]
        }
    ]
}

The following parameters are worth noting:

Parameter	Type	Description
audio_format	string	The audio format of the source file.
channels	array[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_rate	integer	The sampling rate (Hz) of the audio in the source file.
original_duration_in_milliseconds	integer	The original audio duration (ms) in the source file.
channel_id	integer	The track index of the transcription result, starting from 0.
content_duration	integer	The 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.
transcript	string	The paragraph-level transcription result.
sentences	array	The sentence-level transcription result.
words	array	The word-level transcription result.
begin_time	integer	The start timestamp (ms).
end_time	integer	The end timestamp (ms).
text	string	The transcription result.
speaker_id	integer	The 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.
punctuation	string	The punctuation predicted after the word, if any.

​How it works

​Service endpoints

​Request headers

​Submit task interface

Request body

Response body

​Query task interface

Request body

Response body

​Other interfaces: batch-query task status / cancel a task

​Recognition result description

How it works

Service endpoints

Request headers

Submit task interface

Query task interface

Other interfaces: batch-query task status / cancel a task

Recognition result description