Non-real-time speech recognition (Qwen-ASR) API reference

User guide: See Non-real-time speech recognition.

Model connection types

Different models support different connection types.

Model	Connection type
Qwen3-ASR-Flash-Filetrans	Only DashScope asynchronous invocation is supported
Qwen3-ASR-Flash	OpenAI compatible and DashScope synchronous

OpenAI compatible

The US region does not support the OpenAI-compatible mode.

URL

Singapore
US (Virginia)
China (Beijing)

HTTP request address: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completionsbase_url for SDK calls: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1Replace {WorkspaceId} with your actual workspace 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.

Request body

modelstring(Required)The model name. This parameter applies only to the Qwen3-ASR-Flash model.messagesarray(Required)The list of messages.

Message types

System Messageobject (Optional)Used to provide context for speech recognition, such as background text and entity glossaries. Does not support setting model role or other traditional system prompts. If you use a system message, it must be the first message in the messages list.

Properties

rolestring(Required)Set to system.

User Messageobject(Required)The message sent by the user to the model.

Properties

contentarray(Required)The content of the user message. Only one message is allowed in the array.

Properties

typestring(Required)Set to input_audio, which indicates that the input is audio.input_audiostring(Required)The audio to be recognized. For more information about how to use this parameter, see Quick start.In OpenAI-compatible mode, the Qwen3-ASR-Flash model supports two input formats: Base64-encoded files and URLs of audio files that are accessible over the public network.When you use an SDK, if the audio file is stored in OSS, temporary URLs that start with oss:// are not supported.When you use a RESTful API, if the audio file is stored in OSS, temporary URLs that start with oss:// are supported. Note:

Temporary URLs are valid for 48 hours. After expiration, they cannot be used. Do not use them in production environments.
The file upload credential API is rate-limited to 100 QPS and cannot be scaled up. Do not use it in production, high-concurrency, or stress testing scenarios.
For production environments, we recommend using stable storage services such as Alibaba Cloud OSS to ensure long-term file availability and avoid rate limiting issues.

rolestring(Required)The role of the user message. Set to user.

asr_optionsobject(Optional)Specifies whether to enable certain features.

asr_options is not a standard OpenAI parameter. If you use an OpenAI SDK, pass it through extra_body.

Properties

language string (Optional) No default valueIf the language of the audio is known, you can specify it using this parameter to improve recognition accuracy.You can specify only one language.If the audio language is uncertain or includes multiple languages (such as a mix of Chinese, English, Japanese, and Korean), do not specify this parameter.

Valid values

zh: Chinese (Mandarin, Sichuanese, Minnan, and Wu)
yue: Cantonese
en: English
ja: Japanese
de: German
ko: Korean
ru: Russian
fr: French
pt: Portuguese
ar: Arabic
it: Italian
es: Spanish
hi: Hindi
id: Indonesian
th: Thai
tr: Turkish
uk: Ukrainian
vi: Vietnamese
cs: Czech
da: Danish
fil: Filipino
fi: Finnish
is: Icelandic
ms: Malay
no: Norwegian
pl: Polish
sv: Swedish

enable_itnboolean (Optional) Defaults to: falseSpecifies whether to enable Inverse Text Normalization (ITN). This feature applies only to Chinese and English audio.

true
false (default)

streamboolean(Optional) Defaults to: falseSpecifies whether to use streaming output. See Streaming output.Valid values:

false: The model returns the complete content after generation.
true: The model generates and outputs content simultaneously. A data block (chunk) is returned each time a part of the content is generated. You must read these blocks in real time to assemble the complete reply.

Set to true to reduce the risk of request timeouts.stream_optionsobject(Optional)The configuration items for streaming output. This parameter takes effect only when stream is set to true.

Properties

include_usageboolean(Optional) Defaults to: falseSpecifies whether to include token consumption information in the last data block of the response.Valid values:

true
false (default)

During streaming output, token consumption information appears only in the last data block of the response.

Input: audio file URL
Input: Base64-encoded audio file

Python SDK
Node.js SDK
cURL

from openai import OpenAI
import os

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

    stream_enabled = False  # Whether to enable streaming output
    completion = client.chat.completions.create(
        model="qwen3-asr-flash",
        messages=[
            {
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": "{YOUR_AUDIO_URL}"
                        }
                    }
                ],
                "role": "user"
            }
        ],
        stream=stream_enabled,
        # When stream is set to False, the stream_options parameter cannot be set
        # stream_options={"include_usage": True},
        extra_body={
            "asr_options": {
                # "language": "zh",
                "enable_itn": False
            }
        }
    )
    if stream_enabled:
        full_content = ""
        print("The streaming output is:")
        for chunk in completion:
            # If stream_options.include_usage is True, the choices field of the last chunk is an empty list and needs to be skipped (you can get the Token usage via chunk.usage)
            print(chunk)
            if chunk.choices and chunk.choices[0].delta.content:
                full_content += chunk.choices[0].delta.content
        print(f"The complete content is: {full_content}")
    else:
        print(f"The non-streaming output is: {completion.choices[0].message.content}")
except Exception as e:
    print(f"Error message: {e}")

// Preparations before running:
// Common to Windows/Mac/Linux:
// 1. Make sure Node.js is installed (version >= 14 recommended)
// 2. Run the following command to install the required dependencies: npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  // The API Key differs between the Singapore/US regions and the Beijing region. Get an API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
  // If you have not configured the environment variable, replace the following line with your Alibaba Cloud Model Studio API Key: apiKey: "sk-xxx",
  apiKey: process.env.DASHSCOPE_API_KEY,
  // The following is the configuration for the Singapore region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
  baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});

async function main() {
  try {
    const streamEnabled = false; // Whether to enable streaming output
    const completion = await client.chat.completions.create({
      model: "qwen3-asr-flash",
      messages: [
        {
          role: "user",
          content: [
            {
              type: "input_audio",
              input_audio: {
                data: "{YOUR_AUDIO_URL}"
              }
            }
          ]
        }
      ],
      stream: streamEnabled,
      // When stream is set to False, the stream_options parameter cannot be set
      // stream_options: {
      //   "include_usage": true
      // },
      asr_options: {
        // language: "zh",
        enable_itn: false
      }
    });

    if (streamEnabled) {
      let fullContent = "";
      console.log("The streaming output is:");
      for await (const chunk of completion) {
        console.log(JSON.stringify(chunk));
        if (chunk.choices && chunk.choices.length > 0) {
          const delta = chunk.choices[0].delta;
          if (delta && delta.content) {
            fullContent += delta.content;
          }
        }
      }
      console.log(`The complete content is: ${fullContent}`);
    } else {
      console.log(`The non-streaming output is: ${completion.choices[0].message.content}`);
    }
  } catch (err) {
    console.error(`Error message: ${err}`);
  }
}

main();

The following configuration is for the Singapore region. Replace {WorkspaceId} with your actual Workspace ID. The configuration differs by region.

curl -X POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3-asr-flash",
    "messages": [
        {
            "content": [
                {
                    "type": "input_audio",
                    "input_audio": {
                        "data": "{YOUR_AUDIO_URL}"
                    }
                }
            ],
            "role": "user"
        }
    ],
    "stream":false,
    "asr_options": {
        "enable_itn": false
    }
}'

Pass Base64-encoded data as a Data URL in the format data:<mediatype>;base64,<data>.

<mediatype>: the MIME type. The MIME type varies by audio format. For example:
- WAV: audio/wav
- MP3: audio/mpeg
<data>: the Base64-encoded string of the audio. Base64 encoding increases the data size. Keep the source file small enough that the encoded result still meets the input audio size limit (10 MB).

Example: data:audio/wav;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4LjI5LjEwMAAAAAAAAAAAAAAA//PAxABQ/BXRbMPe4IQAhl9

Click to view sample code

import base64, pathlib

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

import java.nio.file.*;
import java.util.Base64;

public class Main {
    /**
     * filePath is the local audio file used for voice cloning. Replace it with the path to your own audio file and make sure it meets the audio requirements.
     */
    public static String toDataUrl(String filePath) throws Exception {
        byte[] bytes = Files.readAllBytes(Paths.get(filePath));
        String encoded = Base64.getEncoder().encodeToString(bytes);
        return "data:audio/mpeg;base64," + encoded;
    }

    // Usage example
    public static void main(String[] args) throws Exception {
        System.out.println(toDataUrl("{YOUR_AUDIO_FILE}"));
    }
}

Python SDK

import base64
from openai import OpenAI
import os
import pathlib

try:
    # Replace with the actual audio file path
    file_path = "{YOUR_AUDIO_FILE}"
    # Replace with the actual MIME type of the audio file
    audio_mime_type = "audio/mpeg"

    file_path_obj = pathlib.Path(file_path)
    if not file_path_obj.exists():
        raise FileNotFoundError(f"Audio file does not exist: {file_path}")

    base64_str = base64.b64encode(file_path_obj.read_bytes()).decode()
    data_uri = f"data:{audio_mime_type};base64,{base64_str}"

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

    stream_enabled = False  # Whether to enable streaming output
    completion = client.chat.completions.create(
        model="qwen3-asr-flash",
        messages=[
            {
                "content": [
                    {
                        "type": "input_audio",
                        "input_audio": {
                            "data": data_uri
                        }
                    }
                ],
                "role": "user"
            }
        ],
        stream=stream_enabled,
        # When stream is set to False, the stream_options parameter cannot be set
        # stream_options={"include_usage": True},
        extra_body={
            "asr_options": {
                # "language": "zh",
                "enable_itn": False
            }
        }
    )
    if stream_enabled:
        full_content = ""
        print("The streaming output is:")
        for chunk in completion:
            # If stream_options.include_usage is True, the choices field of the last chunk is an empty list and needs to be skipped (you can get the Token usage via chunk.usage)
            print(chunk)
            if chunk.choices and chunk.choices[0].delta.content:
                full_content += chunk.choices[0].delta.content
        print(f"The complete content is: {full_content}")
    else:
        print(f"The non-streaming output is: {completion.choices[0].message.content}")
except Exception as e:
    print(f"Error message: {e}")

Response body

idstringThe unique identifier for this call.choicesarrayThe output information from the model.

Properties

finish_reasonstringValid values:

null: The output is still being generated.
stop: The output ended naturally or was terminated by a stop condition.
length: The output exceeded the maximum length limit.

indexintegerThe index of the current object in the choices array.messageobjectThe message object output by the model.

Properties

rolestringThe role of the output message. Set to assistant.contentarrayThe speech recognition result.annotationsarrayThe output annotation information, such as the language.

Properties

languagestringThe language of the recognized audio. If the language request parameter is specified, this value is the same as the specified parameter.

Valid values

zh: Chinese (Mandarin, Sichuanese, Minnan, and Wu)
yue: Cantonese
en: English
ja: Japanese
de: German
ko: Korean
ru: Russian
fr: French
pt: Portuguese
ar: Arabic
it: Italian
es: Spanish
hi: Hindi
id: Indonesian
th: Thai
tr: Turkish
uk: Ukrainian
vi: Vietnamese
cs: Czech
da: Danish
fil: Filipino
fi: Finnish
is: Icelandic
ms: Malay
no: Norwegian
pl: Polish
sv: Swedish

typestringSet to audio_info, which indicates audio information.emotionstringThe emotion of the recognized audio. The following emotions are supported:

surprised: surprised
neutral: neutral
happy: happy
sad: sad
disgusted: disgusted
angry: angry
fearful: fearful

createdintegerThe UNIX timestamp (in seconds) when the request was created.modelstringThe model used for this request.objectstringAlways chat.completion.usageobjectThe token consumption information for this request.

Properties

completion_tokens integerThe number of tokens in the model output.completion_tokens_details objectThe fine-grained details of the tokens in the model output.

Properties

text_tokens integerThe number of tokens in the model output text.

prompt_tokens objectThe number of tokens in the input.prompt_tokens_details objectThe fine-grained details of the tokens in the input.

Properties

audio_tokens integerThe length of the input audio in tokens. Audio-to-token conversion rule: Each second of audio is converted to 25 tokens. Durations less than 1 second are counted as 1 second.text_tokens integerYou can ignore this parameter.

seconds integerThe audio duration in seconds.total_tokens integerThe total number of input and output tokens (total_tokens = completion_tokens + prompt_tokens).

{
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "message": {
                "annotations": [
                    {
                        "emotion": "neutral",
                        "language": "zh",
                        "type": "audio_info"
                    }
                ],
                "content": "Welcome to Alibaba Cloud.",
                "role": "assistant"
            }
        }
    ],
    "created": 1767683986,
    "id": "chatcmpl-487abe5f-d4f2-9363-a877-xxxxxxx",
    "model": "qwen3-asr-flash",
    "object": "chat.completion",
    "usage": {
        "completion_tokens": 12,
        "completion_tokens_details": {
            "text_tokens": 12
        },
        "prompt_tokens": 42,
        "prompt_tokens_details": {
            "audio_tokens": 42,
            "text_tokens": 0
        },
        "seconds": 1,
        "total_tokens": 54
    }
}

DashScope synchronous

URL

Singapore
US (Virginia)
China (Beijing)

HTTP request address: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generationbase_url for SDK calls: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Replace {WorkspaceId} with your actual workspace ID.Replace {WorkspaceId} with your actual workspace ID.

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.

Request body

modelstring(Required)The model name. This parameter applies only to the Qwen3-ASR-Flash model.messagesarray(Required)The list of messages.

When you make an HTTP call, place messages in the input object.

Message types

System Messageobject (Optional)Used to provide context for speech recognition, such as background text and entity glossaries. Does not support setting model role or other traditional system prompts. If you set a system message, place it at the beginning of the messages list.Only Qwen3-ASR-Flash supports this parameter.

Properties

rolestring(Required)Set to system.

User Messageobject(Required)The message sent by the user to the model.

Properties

contentarray(Required)The content of the user message. Only one message is allowed in the array.

Properties

audiostring(Required)The audio to be recognized. For more information about how to use this parameter, see Quick start.When you use DashScope, the Qwen3-ASR-Flash model supports three input formats: Base64-encoded files, absolute paths of local files, and URLs of audio files that are accessible over the public network.When you use an SDK, if the audio file is stored in OSS, temporary URLs that start with oss:// are not supported.When you use a RESTful API, if the audio file is stored in OSS, temporary URLs that start with oss:// are supported. Note:

Temporary URLs are valid for 48 hours. After expiration, they cannot be used. Do not use them in production environments.
The file upload credential API is rate-limited to 100 QPS and cannot be scaled up. Do not use it in production, high-concurrency, or stress testing scenarios.
For production environments, we recommend using stable storage services such as Alibaba Cloud OSS to ensure long-term file availability and avoid rate limiting issues.

rolestring(Required)The role of the user message. Set to user.

asr_optionsobject(Optional)Specifies whether to enable certain features.This parameter is supported only by the Qwen3-ASR-Flash model.

Properties

Valid values

zh: Chinese (Mandarin, Sichuanese, Minnan, and Wu)
yue: Cantonese
en: English
ja: Japanese
de: German
ko: Korean
ru: Russian
fr: French
pt: Portuguese
ar: Arabic
it: Italian
es: Spanish
hi: Hindi
id: Indonesian
th: Thai
tr: Turkish
uk: Ukrainian
vi: Vietnamese
cs: Czech
da: Danish
fil: Filipino
fi: Finnish
is: Icelandic
ms: Malay
no: Norwegian
pl: Polish
sv: Swedish

enable_itnboolean (Optional) Defaults to: falseSpecifies whether to enable Inverse Text Normalization (ITN). This feature applies only to Chinese and English audio.

true
false (default)

The following example shows how to recognize an audio file from a URL. For an example of how to recognize a local audio file, see Quick start.

curl -X POST "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen3-asr-flash",
    "input": {
        "messages": [
            {
                "content": [
                    {
                        "audio": "{YOUR_AUDIO_URL}"
                    }
                ],
                "role": "user"
            }
        ]
    },
    "parameters": {
        "asr_options": {
            "enable_itn": false
        }
    }
}'

Response body

request_idstringThe unique identifier for this call.

The parameter returned by the Java SDK is requestId

outputobjectThe call result information.

Properties

choicesarrayThe model output. Returned when result_format is message.

Properties

finish_reasonstringValid values:

null: The output is still being generated.
stop: The output ended naturally or was terminated by a stop condition.
length: The output exceeded the maximum length limit.

messageobjectThe message object output by the model.

Properties

rolestringThe role of the output message. Set to assistant.contentarrayThe content of the output message.

Properties

textstringThe speech recognition result.

annotationsarrayThe output annotation information, such as the language.

Properties

languagestringThe language of the recognized audio. If the language request parameter is specified, this value is the same as the specified parameter.

Valid values

zh: Chinese (Mandarin, Sichuanese, Minnan, and Wu)
yue: Cantonese
en: English
ja: Japanese
de: German
ko: Korean
ru: Russian
fr: French
pt: Portuguese
ar: Arabic
it: Italian
es: Spanish
hi: Hindi
id: Indonesian
th: Thai
tr: Turkish
uk: Ukrainian
vi: Vietnamese
cs: Czech
da: Danish
fil: Filipino
fi: Finnish
is: Icelandic
ms: Malay
no: Norwegian
pl: Polish
sv: Swedish

typestringSet to audio_info, which indicates audio information.emotionstringThe emotion of the recognized audio. The following emotions are supported:

surprised: surprised
neutral: neutral
happy: happy
sad: sad
disgusted: disgusted
angry: angry
fearful: fearful

usageobjectThe token consumption information for this request.

Properties

input_tokens_details objectThe length of the input content for Qwen3-ASR-Flash in tokens.

Properties

text_tokens integerYou can ignore this parameter.

output_tokens_details objectThe length of the output content from Qwen3-ASR-Flash in tokens.

Properties

text_tokens integerThe length of the recognized text output by Qwen3-ASR-Flash in tokens.

seconds integerThe audio duration for Qwen3-ASR-Flash in seconds.

{
    "output": {
        "choices": [
            {
                "finish_reason": "stop",
                "message": {
                    "annotations": [
                        {
                            "language": "zh",
                            "type": "audio_info",
                            "emotion": "neutral"
                        }
                    ],
                    "content": [
                        {
                            "text": "Welcome to Alibaba Cloud."
                        }
                    ],
                    "role": "assistant"
                }
            }
        ]
    },
    "usage": {
        "input_tokens_details": {
            "text_tokens": 0
        },
        "output_tokens_details": {
            "text_tokens": 6
        },
        "seconds": 1
    },
    "request_id": "568e2bf0-d6f2-97f8-9f15-a57b11dc6977"
}

DashScope asynchronous invocation

Process description

Asynchronous invocation is designed for long audio files or time-consuming tasks. It uses a two-step "submit-poll" process to prevent request timeouts:

Step 1: Submit a task
- The client initiates an asynchronous processing request.
- After validating the request, the server does not execute the task immediately. Instead, it returns a unique task_id, indicating that the task has been successfully created.
Step 2: Obtain the result
- The client uses the task_id to poll the result query API.
- When the task is complete, the result query API returns the final recognition result.

You can choose to use an SDK or call the RESTful API directly based on your integration environment.

Use an SDK. For sample code, see QuickStart. For request parameters, see the Request body of the Submit a task operation. For information about the response, see Description of asynchronous call results. SDKs handle the underlying API call details automatically.
1. Submit a task: Call the async_call() (Python) or asyncCall() (Java) method to submit the task. This method returns a task object containing a task_id.
2. Obtain the result: Use the task object returned in the previous step or the task_id to call the fetch() method to retrieve the result. The SDK automatically handles the internal polling logic until the task is complete or times out.
Use a RESTful API Calling the RESTful API directly provides maximum flexibility.
1. Submit the task. If the request is successful, the response body will contain a task_id.
2. Use the task_id from the previous step to retrieve the task execution result.

Submit a task

URL

Singapore
China (Beijing)

HTTP request address: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcriptionbase_url for SDK calls: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Replace {WorkspaceId} with your actual workspace ID.Replace {WorkspaceId} with your actual workspace ID.

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.

Request body

modelstring(Required)The model name. This parameter applies only to the Qwen3-ASR-Flash-Filetrans model.inputobject(Required)

Properties

file_url string(Required)The URL of the audio file to be recognized. The URL must be accessible over the public network.When you use an SDK, if the audio file is stored in OSS, temporary URLs that start with oss:// are not supported.When you use a RESTful API, if the audio file is stored in OSS, temporary URLs that start with oss:// are supported. Note:

Temporary URLs are valid for 48 hours. After expiration, they cannot be used. Do not use them in production environments.
The file upload credential API is rate-limited to 100 QPS and cannot be scaled up. Do not use it in production, high-concurrency, or stress testing scenarios.
For production environments, we recommend using stable storage services such as Alibaba Cloud OSS to ensure long-term file availability and avoid rate limiting issues.

parametersobject(Optional)

Properties

Valid values

zh: Chinese (Mandarin, Sichuanese, Minnan, and Wu)
yue: Cantonese
en: English
ja: Japanese
de: German
ko: Korean
ru: Russian
fr: French
pt: Portuguese
ar: Arabic
it: Italian
es: Spanish
hi: Hindi
id: Indonesian
th: Thai
tr: Turkish
uk: Ukrainian
vi: Vietnamese
cs: Czech
da: Danish
fil: Filipino
fi: Finnish
is: Icelandic
ms: Malay
no: Norwegian
pl: Polish
sv: Swedish

enable_itnboolean (Optional) Defaults to: falseSpecifies whether to enable Inverse Text Normalization (ITN). This feature applies only to Chinese and English audio.

true
false (default)

enable_wordsboolean(Optional) Defaults to: falseSpecifies whether to return word-level timestamps:

false: Returns sentence-level timestamps.
true: Returns word-level timestamps. Word-level timestamps are supported only for the following languages: Chinese, English, Japanese, Korean, German, French, Spanish, Italian, Portuguese, and Russian. Accuracy for other languages cannot be guaranteed.

This parameter also affects the sentence segmentation rules:

false: Sentence segmentation is based on Voice Activity Detection (VAD).
true: Sentence segmentation is based on VAD and punctuation.

channel_idarray(Optional) Defaults to: [0]Specifies the indexes of the audio tracks to be recognized in a multi-track audio file. The index starts from 0. For example, [0] indicates that the first audio track is recognized, and [0, 1] indicates that the first and second audio tracks are recognized simultaneously. If this parameter is omitted, the first audio track is processed by default.

Each specified audio track is billed separately. For example, requesting [0, 1] for a single file will incur two separate charges.

cURL
Java
Python

# ======= Important =======
# The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
# The API keys for the Singapore and Beijing regions are different. For more information about how to obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# === Delete this comment before running the command. ===

curl --location --request POST '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": "qwen3-asr-flash-filetrans",
    "input": {
        "file_url": "{YOUR_AUDIO_URL}"
    },
    "parameters": {
        "channel_id":[
            0
        ],
        "enable_itn": false
    }
}'

For SDK examples, see QuickStart.

import com.google.gson.Gson;
import com.google.gson.annotations.SerializedName;
import okhttp3.*;

import java.io.IOException;

public class Main {
    // The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
    private static final String API_URL = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription";

    public static void main(String[] args) {
        // The API keys for the Singapore and Beijing regions are different. For more information about how to obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
        // If the environment variable is not configured, replace the following line with your Model Studio API key: String apiKey = "sk-xxx"
        String apiKey = System.getenv("DASHSCOPE_API_KEY");

        OkHttpClient client = new OkHttpClient();
        Gson gson = new Gson();

        /*String payloadJson = """
                {
                    "model": "qwen3-asr-flash-filetrans",
                    "input": {
                        "file_url": "{YOUR_AUDIO_URL}"
                    },
                    "parameters": {
                        "channel_id": [0],
                        "enable_itn": false,
                        "language": "zh",
                        "corpus": {
                            "text": ""
                        }
                    }
                }
                """;*/
        String payloadJson = """
                {
                    "model": "qwen3-asr-flash-filetrans",
                    "input": {
                        "file_url": "{YOUR_AUDIO_URL}"
                    },
                    "parameters": {
                        "channel_id": [0],
                        "enable_itn": false
                    }
                }
                """;

        RequestBody body = RequestBody.create(payloadJson, MediaType.get("application/json; charset=utf-8"));
        Request request = new Request.Builder()
                .url(API_URL)
                .addHeader("Authorization", "Bearer " + apiKey)
                .addHeader("Content-Type", "application/json")
                .addHeader("X-DashScope-Async", "enable")
                .post(body)
                .build();

        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                String respBody = response.body().string();
                // Parse JSON using Gson
                ApiResponse apiResp = gson.fromJson(respBody, ApiResponse.class);
                if (apiResp.output != null) {
                    System.out.println("task_id: " + apiResp.output.taskId);
                } else {
                    System.out.println(respBody);
                }
            } else {
                System.out.println("task failed! HTTP code: " + response.code());
                if (response.body() != null) {
                    System.out.println(response.body().string());
                }
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }

    static class ApiResponse {
        @SerializedName("request_id")
        String requestId;

        Output output;
    }

    static class Output {
        @SerializedName("task_id")
        String taskId;

        @SerializedName("task_status")
        String taskStatus;
    }
}

For SDK examples, see QuickStart.

import requests
import json
import os

# The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription"

# The API keys for the Singapore and Beijing regions are different. For more information about how to obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If the environment variable is not configured, replace the following line with your Model Studio API key: DASHSCOPE_API_KEY = "sk-xxx"
DASHSCOPE_API_KEY = os.getenv("DASHSCOPE_API_KEY")

headers = {
    "Authorization": f"Bearer {DASHSCOPE_API_KEY}",
    "Content-Type": "application/json",
    "X-DashScope-Async": "enable"
}

payload = {
    "model": "qwen3-asr-flash-filetrans",
    "input": {
        "file_url": "{YOUR_AUDIO_URL}"
    },
    "parameters": {
        "channel_id": [0],
        # "language": "zh",
        "enable_itn": False
        # "corpus": {
        #     "text": ""
        # }
    }
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
if response.status_code == 200:
    print(f"task_id: {response.json()["output"]["task_id"]}")
else:
    print("task failed!")
    print(response.json())

Response body

request_idstringThe unique identifier for this call.outputobjectThe call result information.

Properties

task_idstringThe task ID. This ID is passed as a request parameter in the API for querying speech recognition tasks.task_statusstringThe task status:

PENDING
RUNNING
SUCCEEDED
FAILED
UNKNOWN: The task does not exist or its status is unknown.

{
    "request_id": "92e3decd-0c69-47a8-************",
    "output": {
        "task_id": "8fab76d0-0eed-4d20-************",
        "task_status": "PENDING"
    }
}

Get the task execution result

URL

Singapore
China (Beijing)

HTTP request address: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}base_url for SDK calls: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Replace {WorkspaceId} with your actual workspace ID.Replace {WorkspaceId} with your actual workspace ID.

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.

Request body

task_idstring(Required)The task ID. Pass the task_id from the response of the Submit a task operation to query the speech recognition result.

cURL
Java
Python

# ======= Important =======
# The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
# The API keys for the Singapore and Beijing regions are different. For more information about how to obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# === Delete this comment before running the command. ===

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

For SDK examples, see QuickStart.

import okhttp3.*;

import java.io.IOException;

public class Main {
    public static void main(String[] args) {
        // Replace with the actual task_id.
        String taskId = "xxx";
        // The API keys for the Singapore and Beijing regions are different. For more information about how to obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
        // If the environment variable is not configured, replace the following line with your Model Studio API key: String apiKey = "sk-xxx"
        String apiKey = System.getenv("DASHSCOPE_API_KEY");

        // The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
        String apiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/" + taskId;

        OkHttpClient client = new OkHttpClient();

        Request request = new Request.Builder()
                .url(apiUrl)
                .addHeader("Authorization", "Bearer " + apiKey)
                .addHeader("Content-Type", "application/json")
                .get()
                .build();

        try (Response response = client.newCall(request).execute()) {
            if (response.body() != null) {
                System.out.println(response.body().string());
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

For SDK examples, see QuickStart.

import os
import requests

# The API keys for the Singapore and Beijing regions are different. For more information about how to obtain an API key, see https://www.alibabacloud.com/help/en/model-studio/get-api-key
# If the environment variable is not configured, replace the following line with your Model Studio API key: DASHSCOPE_API_KEY = "sk-xxx"
DASHSCOPE_API_KEY = os.getenv("DASHSCOPE_API_KEY")

# Replace with the actual task_id.
task_id = "xxx"
# The following configuration is for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
url = f"https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}"

headers = {
    "Authorization": f"Bearer {DASHSCOPE_API_KEY}",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

Response body

request_idstringThe unique identifier for this call.outputobjectThe call result information.

Properties

task_idstringThe task ID. This ID is passed as a request parameter in the API for querying speech recognition tasks.task_statusstringThe task status:

PENDING
RUNNING
SUCCEEDED
FAILED
UNKNOWN: The task does not exist or its status is unknown.

resultobjectThe speech recognition result.

Properties

transcription_urlstringThe download URL for the recognition result file. The link is valid for 24 hours. After the link expires, you cannot query the task or download the result using the previous URL.
The recognition result is saved as a JSON file. You can download the file from this link or read the file content directly using an HTTP request.
For more information, see Description of asynchronous call results.

submit_timestringThe time when the task was submitted.schedule_timestringThe time when the task was scheduled, which is the start time of execution.end_timestringThe time when the task ended.task_metricsobjectTask metrics, which include statistics on the status of subtasks.

Properties

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

codestringThe error code. This is returned only when the task fails.messagestringThe error message. This is returned only when the task fails.usageobjectThe token consumption information for this request.

Properties

seconds integerThe audio duration for Qwen3-ASR-Flash in seconds.

{
    "request_id": "6769df07-2768-4fb0-ad59-************",
    "output": {
        "task_id": "9be1700a-0f8e-4778-be74-************",
        "task_status": "RUNNING",
        "submit_time": "2025-10-27 14:19:31.150",
        "scheduled_time": "2025-10-27 14:19:31.233",
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 0,
            "FAILED": 0
        }
    }
}

Description of asynchronous call results

file_url stringThe URL of the recognized audio file.audio_infoobjectInformation about the recognized audio file.

Properties

format stringThe audio format.sample_rate integerThe audio sampling rate.

transcriptsarrayA list of complete recognition results. Each element corresponds to the recognized content of an audio track.

Properties

channel_idintegerThe audio track index, starting from 0.textstringThe recognized text.sentencesobjectA list of sentence-level recognition results.

Properties

begin_time integerThe start timestamp of the sentence in milliseconds.end_time integerThe end timestamp of the sentence in milliseconds.textstringThe recognized text.sentence_idintegerThe sentence index, starting from 0.languagestringThe language of the recognized audio. If the language request parameter is specified, this value is the same as the specified parameter.

Valid values

zh: Chinese (Mandarin, Sichuanese, Minnan, and Wu)
yue: Cantonese
en: English
ja: Japanese
de: German
ko: Korean
ru: Russian
fr: French
pt: Portuguese
ar: Arabic
it: Italian
es: Spanish
hi: Hindi
id: Indonesian
th: Thai
tr: Turkish
uk: Ukrainian
vi: Vietnamese
cs: Czech
da: Danish
fil: Filipino
fi: Finnish
is: Icelandic
ms: Malay
no: Norwegian
pl: Polish
sv: Swedish

emotionstringThe emotion of the recognized audio. The following emotions are supported:

surprised
neutral
happy
sad
disgusted
angry
fearful

wordsobjectA list of word-level recognition results. This result is displayed when the enable_words request parameter is set to true.

Properties

begin_time integerThe start timestamp in milliseconds.end_time integerThe end timestamp in milliseconds.textstringThe recognized text.punctuationstringThe punctuation mark.

{
    "file_url": "https://***.wav",
    "audio_info": {
        "format": "wav",
        "sample_rate": 16000
    },
    "transcripts": [
        {
            "channel_id": 0,
            "text": "Senior staff, Principal Doris Jackson, Wakefield faculty, and of course my fellow classmates.I am honored to have been chosen to speak before my classmates along with the students across America today.",
            "sentences": [
                {
                    "sentence_id": 0,
                    "begin_time": 240,
                    "end_time": 6720,
                    "language": "en",
                    "emotion": "happy",
                    "text": "Senior staff, Principal Doris Jackson, Wakefield faculty, and of course my fellow classmates.",
                    "words": [
                        {
                            "begin_time": 240,
                            "end_time": 1120,
                            "text": "Senior ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 1120,
                            "end_time": 1200,
                            "text": "staff",
                            "punctuation": ","
                        },
                        {
                            "begin_time": 1680,
                            "end_time": 1920,
                            "text": " Principal ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 2000,
                            "end_time": 2320,
                            "text": "Doris ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 2320,
                            "end_time": 2960,
                            "text": "Jackson",
                            "punctuation": ","
                        },
                        {
                            "begin_time": 3360,
                            "end_time": 3840,
                            "text": " Wakefield ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 3840,
                            "end_time": 4480,
                            "text": "faculty",
                            "punctuation": ","
                        },
                        {
                            "begin_time": 4800,
                            "end_time": 4960,
                            "text": " and ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 4960,
                            "end_time": 5040,
                            "text": "of ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 5040,
                            "end_time": 5520,
                            "text": "course ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 5520,
                            "end_time": 5680,
                            "text": "my ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 5760,
                            "end_time": 6000,
                            "text": "fellow ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 6000,
                            "end_time": 6720,
                            "text": "classmates",
                            "punctuation": "."
                        }
                    ]
                },
                {
                    "sentence_id": 1,
                    "begin_time": 12268,
                    "end_time": 17388,
                    "language": "en",
                    "emotion": "neutral",
                    "text": "I am honored to have been chosen to speak before my classmates along with the students across America today.",
                    "words": [
                        {
                            "begin_time": 12268,
                            "end_time": 12428,
                            "text": "I ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 12428,
                            "end_time": 12508,
                            "text": "am ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 12588,
                            "end_time": 12828,
                            "text": "honored ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 12908,
                            "end_time": 12908,
                            "text": "to ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 12908,
                            "end_time": 13068,
                            "text": "have ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 13068,
                            "end_time": 13228,
                            "text": "been ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 13228,
                            "end_time": 13628,
                            "text": "chosen ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 13628,
                            "end_time": 13708,
                            "text": "to ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 13708,
                            "end_time": 14028,
                            "text": "speak ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 14028,
                            "end_time": 14268,
                            "text": "before ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 14268,
                            "end_time": 14428,
                            "text": "my ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 14428,
                            "end_time": 15148,
                            "text": "classmates ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 15308,
                            "end_time": 15468,
                            "text": "as ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 15468,
                            "end_time": 15628,
                            "text": "well ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 15628,
                            "end_time": 15788,
                            "text": "as ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 15788,
                            "end_time": 15788,
                            "text": "the ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 15788,
                            "end_time": 16188,
                            "text": "students ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 16188,
                            "end_time": 16588,
                            "text": "across ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 16588,
                            "end_time": 16988,
                            "text": "America ",
                            "punctuation": ""
                        },
                        {
                            "begin_time": 16988,
                            "end_time": 17388,
                            "text": "today",
                            "punctuation": "."
                        }
                    ]
                }
            ]
        }
    ]
}

​Model connection types

​OpenAI compatible

​URL

Request body

Response body

​DashScope synchronous

​URL

Request body

Response body

​DashScope asynchronous invocation

​Process description

​Submit a task

​URL

Request body

Response body

​Get the task execution result

​URL

Request body

Response body

Description of asynchronous call results

Model connection types

OpenAI compatible

URL

DashScope synchronous

URL

DashScope asynchronous invocation

Process description

Submit a task

URL

Get the task execution result

URL