Skip to main content
Non-realtime

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

File transcription REST

This topic describes the parameters and interface details of the HTTP API for non-real-time speech recognition with Qwen-Audio-3.0-ASR-Flash-Filetrans and Fun-ASR. 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:
  1. 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.
  2. 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.

Prerequisites

Sign in to QwenCloud and create an API key. To avoid security risks, export the API key as an environment variable instead of hard-coding it.
To grant temporary access or restrict sensitive operations, use a temporary token.Temporary tokens expire in 60 seconds, reducing leakage risk. Replace the API key in your code with the temporary token.

Service endpoints

Submit task interface: POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/transcription Query task interface: GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

Request headers

ParameterTypeRequiredDescription
AuthorizationstringYesAuthentication token in the format Bearer $DASHSCOPE_API_KEY. Replace "<your_api_key>" with your actual API key. Required for both the submit task interface and the query task interface.
Content-TypestringYesThe media type of the request body. Required only for the submit task interface. Fixed value: application/json.
X-DashScope-AsyncstringYesThe 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.
  • Basic call
  • Inline hotwords
  • Context
curl --location 'https://dashscope-intl.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]
    }
}'

Request parameters

ParameterTypeDefault valueRequiredDescription
modelstring-YesThe 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.
file_urlsarray[string]-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.
contextarray(object)-NoA list of messages that provide optional conversation context to improve recognition accuracy. See context parameter details.
vocabulary_idstring-NoThe 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.
vocabularyobject-NoInstant 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.
channel_idarray[integer][0]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.
special_word_filterstring-NoThe 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_enabledbooleanfalseNoWhether 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. See Recognition result description.
speaker_countinteger-NoA reference value for the number of speakers. The valid range is an integer from 2 to 100 (inclusive). Takes effect only when diarization_enabled is set to true. 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.
language_hintsarray[string]-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.
Only qwen-audio-3.0-asr-flash-filetrans supports inline hotwords (vocabulary parameter).
Each audio track in channel_id is billed separately. Example: [0, 1] on one file = two charges.
When speaker diarization is enabled, keep the audio duration within 2 hours. Otherwise, recognition may fail or time out.

context parameter details

The context parameter is 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.

Sensitive word filter details

If special_word_filter is not set, the built-in filter replaces matched words with asterisks (*) of equal length. If set, you can use these policies:
  • Replace with *: Replaces matched words with asterisks of the same length.
  • Filter out: Removes matched words from the result.
The value must be a JSON string:
{
  "filter_with_signed": {
  "word_list": ["test"]
  },
  "filter_with_empty": {
  "word_list": ["start", "happen"]
  },
  "system_reserved_filter": true
}
Field descriptions:
  • filter_with_signed
    • Type: object. Required: No.
    • Matched words are replaced with asterisks of the same length.
    • Example: "Help me test this piece of code" becomes "Help me **** this piece of code".
    • Internal field: word_list -- A string array of words to replace.
  • filter_with_empty
    • Type: object. Required: No.
    • Matched words are removed from the result.
    • Example: "Is the game about to start?" becomes "Is the game about to ?".
    • Internal field: word_list -- A string array of words to remove.
  • system_reserved_filter
    • Type: Boolean. Required: No. Default: true.
    • Enables the system's preset sensitive word rules. When true, words matching the QwenCloud sensitive word list are replaced with asterisks of the same length.

Supported languages

Supported 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 parameters

{
  "output": {
  "task_status": "PENDING",
  "task_id": "c2e5d63b-96e1-4607-bb91-************"
  },
  "request_id": "77ae55ae-be17-97b8-9942-************"
}
ParameterTypeDescription
request_idstringThe unique identifier of this call.
task_statusstringThe task status. Returns PENDING on successful submission.
task_idstringThe task ID. Use it with the Query task interface to check results.

Query task interface

Basic information

ItemDescription
DescriptionQueries the execution status and result of a speech recognition task. Poll this interface until the task reaches a terminal state.
URLhttps://dashscope-intl.aliyuncs.com/api/v1/tasks/\{task_id\}
Request methodGET
Request headersSee below
Message bodyNone
Request headers:
Authorization: Bearer $DASHSCOPE_API_KEY

Request parameters

curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY"
ParameterTypeDefault valueRequiredDescription
task_idstring-YesThis 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.

Response parameters

Multi-subtask jobs: overall status shows SUCCEEDED if any subtask succeeds. Check subtask_status to determine the result of a specific subtask.
{
  "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": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav",
    "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/filetrans-16k/20240912/15%3A11/3bdf7689-b598-409d-806a-121cff5e4a31-1.json?Expires=1726211500&OSSAccessKeyId=yourOSSAccessKeyId&Signature=Fj%2BaF%2FH0Kayj3w3My2ECBeP****%3D",
    "subtask_status": "SUCCEEDED"
      },
      {
    "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=yourOSSAccessKeyId&Signature=v5Owy5qoAfT7mzGmQgH0g8C****%3D",
    "subtask_status": "SUCCEEDED"
      }
  ],
  "task_metrics": {
      "TOTAL": 2,
      "SUCCEEDED": 2,
      "FAILED": 0
  }
  },
  "usage": {
  "duration": 9
  }
}
The code field contains the error code, and the message field contains the error message. These fields appear only on errors.
{
  "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": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/long_audio_demo_cn.mp3",
      "transcription_url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/prod/paraformer-v2/20241216/xxxx",
      "subtask_status": "SUCCEEDED"
    },
    {
      "file_url": "{YOUR_AUDIO_URL}",
      "code": "FILE_DOWNLOAD_FAILED",
      "message": "FILE_DOWNLOAD_FAILED",
      "subtask_status": "FAILED"
    }
  ],
  "task_metrics": {
    "TOTAL": 2,
    "SUCCEEDED": 1,
    "FAILED": 1
  }
}
ParameterTypeDescription
request_idstringThe unique identifier of this call.
task_idstringThe task ID.
task_statusstringThe task status.
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.
submit_timestringThe time the task was submitted.
scheduled_timestringThe time the task was scheduled to run.
end_timestringThe time the task ended.
task_metricsobjectOverall execution statistics for the task: TOTAL, SUCCEEDED (number of successful subtasks), and FAILED counts.
usageobjectUsage information. duration is the total duration in seconds.

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.
{
  "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": ", "
            }
          ]
        }
      ]
    }
  ]
}
The speaker_id field appears only when speaker diarization is enabled. Other word entries are omitted for brevity.
Key parameters:
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_duration_in_millisecondsintegerThe duration (ms) of content in the track that is identified as speech.
textstringThe paragraph-level transcription result.
sentencesarrayThe sentence-level transcription result.
wordsarrayThe word-level transcription result.
begin_timeintegerThe start timestamp (ms).
end_timeintegerThe end timestamp (ms).
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.
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.

Fun-ASR-Flash (synchronous)

SDK calls are not supported for this feature. Use the HTTP API directly.

Basic information

ItemDescription
DescriptionSynchronously transcribes an audio file up to 5 minutes long. Optionally accepts conversation context to improve recognition of proper nouns.
URLhttps://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
Request methodPOST
Request headersSee below
Message bodySee below
Request headers:
Authorization: Bearer $DASHSCOPE_API_KEY
Content-Type: application/json
X-DashScope-SSE: enable
Set X-DashScope-SSE to enable to receive results incrementally over SSE, or to disable (or omit the header) to receive only the final result.

Request parameters

  • Non-streaming
  • Streaming
  • With context
curl --location --request POST 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
     --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
     --header "Content-Type: application/json" \
     --header "X-DashScope-SSE: disable" \
     --data '{
    "model": "fun-asr-flash-2026-06-15",
    "input": {
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"
                        }
                    }
                ]
            }
        ]
    },
    "parameters": {
        "format": "wav",
        "sample_rate": "16000"
    }
}'
ParameterTypeRequiredDescription
modelstringYesSet to fun-asr-flash-2026-06-15.
input.messagesarray[object]YesThe message list. Contains the audio to transcribe and, optionally, conversation context to improve recognition accuracy.
input.messages[].rolestringYesuser: the audio to transcribe (input_audio type), or a previous turn's transcription/word list for context (input_text type). assistant (optional, for context): an LLM response from a previous turn.
input.messages[].content[].typestringYesinput_audio (required, role must be user): the audio to transcribe. input_text (optional, for context, role must be user): a previous transcription result or domain-specific word list. text (optional, for context, role must be assistant): an LLM response from a previous turn.
input.messages[].content[].input_audio.datastringConditionalRequired when type is input_audio. Either a publicly accessible audio file URL or a Base64 Data URI (data:{MIME_TYPE};base64,{DATA}, for example audio/wav or audio/mp3).
input.messages[].content[].textstringConditionalRequired when type is input_text or text. Text length is counted per character; the combined length of all text fields in a turn must not exceed 400 characters, with excess truncated from the end.
parameters.formatstringYesThe audio format, for example wav, mp3, or opus.
parameters.sample_ratestringNoThe audio sample rate in Hz, for example 16000.
Context messages (input_text and text types) are limited to 5 each. When exceeded, only the 5 most recent are retained. The order of messages matters: each user context message must precede its corresponding assistant message, and the user message with input_audio must always be last in input.messages.

Base64

You can provide Base64-encoded audio as a Data URI in the format data:{MIME_TYPE};base64,{DATA}:
  • {MIME_TYPE}: MIME type, which varies by audio format. For example: WAV uses audio/wav, MP3 uses audio/mpeg.
  • {DATA}: The Base64-encoded string of the audio file.
Base64 encoding increases the file size. Keep the original file small enough so the encoded data still meets the audio input size limit (10 MB). Example: data:audio/wav;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4LjI5LjEwMAAAAAAAAAAAAAAA//PAxABQ/BXRbMPe4IQAhl9
  • Python
  • Java
import base64, pathlib

# input.mp3 is the local audio file to recognize. Replace it with the path to your own audio file and make sure it meets the audio requirements.
file_path = pathlib.Path("input.mp3")
base64_str = base64.b64encode(file_path.read_bytes()).decode()
data_uri = f"data:audio/mpeg;base64,{base64_str}"

Response parameters

  • Non-streaming
  • Streaming
{
    "output": {
        "sentence": {
            "begin_time": 760,
            "channel_id": 0,
            "end_time": 3800,
            "sentence_end": true,
            "sentence_id": 1,
            "text": "Hello world, this is Alibaba Speech Lab.",
            "words": [
                {"begin_time": 760, "end_time": 1040, "fixed": true, "punctuation": "", "text": "Hello"},
                {"begin_time": 1040, "end_time": 1360, "fixed": true, "punctuation": ", ", "text": " world"}
            ]
        },
        "text": "Hello world, this is Alibaba Speech Lab."
    },
    "usage": {
        "duration": 4
    },
    "request_id": "40e0734d-096f-9ae3-86c1-a8c013287561"
}
ParameterTypeDescription
request_idstringThe unique identifier of this request.
output.textstringThe accumulated full transcription text up to this point.
output.sentence.sentence_idintegerThe sentence number, starting from 1.
output.sentence.sentence_endbooleanWhether recognition for this sentence is complete.
output.sentence.begin_timeintegerThe sentence start time (ms).
output.sentence.end_timeintegerThe sentence end time (ms). Returned only when sentence_end is true.
output.sentence.textstringThe transcription text for the current sentence.
output.sentence.channel_idintegerThe audio channel number, starting from 0.
output.sentence.wordsarrayThe word-level timestamp list.
output.sentence.words[].textstringThe word text.
output.sentence.words[].begin_timeintegerThe word start time (ms).
output.sentence.words[].end_timeintegerThe word end time (ms).
output.sentence.words[].punctuationstringThe punctuation mark after the word, if any.
output.sentence.words[].fixedbooleanWhether the word is finalized. false means the timestamp may still change in later events.
usage.durationintegerThe duration of processed audio, in seconds. Returned only when sentence_end is true.
For each SSE event, parse the JSON in the data field, and check output.sentence.sentence_end to determine whether the sentence is final. usage is included only in sentence-end events.