Non-real-time speech recognition (Qwen-ASR) API reference
Input and output parameters for the Qwen-ASR model. Call the API using the OpenAI compatible or DashScope protocol.
Model connection types
Different models support different connection types. Select the appropriate type for integration based on the following table.
Model | Connection type |
|---|---|
Qwen3-ASR-Flash-Filetrans | Only DashScope asynchronous invocation is supported |
Qwen3-ASR-Flash |
OpenAI compatible
ImportantThe US region does not support OpenAI-compatible mode.
URL
China (Beijing)
HTTP request address: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/chat/completions
base_url for SDK calls: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
Replace {WorkspaceId} with your actual workspace ID.
Singapore
HTTP request address: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
base_url for SDK calls: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
Replace {WorkspaceId} with your actual workspace ID.
ImportantAlibaba 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.comto{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: from
dashscope-intl.aliyuncs.comto{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Request bodymodel The model name. This parameter applies only to the Qwen3-ASR-Flash model. messages The list of messages. asr_options Specifies whether to enable certain features. Note stream Specifies whether to use streaming output. See Streaming output. Valid values:
We recommend setting this parameter to stream_options The configuration items for streaming output. This parameter takes effect only when | Request examplesNoteUse OpenAI Python SDK version Input: audio file URLPython SDKNode.js SDKcURLThe following configuration is for the China (Beijing) region. Replace Input: Base64-encoded audio filePass Base64-encoded data as a Data URL in the format
|
Response bodyNoteQwen3-ASR-Flash does not return timestamps through the OpenAI-compatible API. For timestamps, use the Qwen-Audio-ASR-Filetrans series. For integration details, see the HTTP API. Emotion labels are returned in id The unique identifier for this call. choices The output information from the model. Properties finish_reason Valid values:
index The index of the current object in the message The message object output by the model. created The UNIX timestamp (in seconds) when the request was created. model The model used for this request. object Always usage The token consumption information for this request. | |
DashScope synchronous
URL
China (Beijing)
HTTP request address: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
base_url for SDK calls: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
Replace {WorkspaceId} with your actual workspace ID.
Singapore
HTTP request address: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
base_url for SDK calls: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1
Replace {WorkspaceId} with your actual workspace ID.
US (Virginia)
HTTP request address: POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
base_url for SDK calls: https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/api/v1
ImportantAlibaba 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.comto{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: from
dashscope-intl.aliyuncs.comto{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Request bodymodel The model name. This parameter applies only to the Qwen3-ASR-Flash model. messages The list of messages. NoteWhen you make an HTTP call, place asr_options Specifies whether to enable certain features. This parameter is supported only by the Qwen3-ASR-Flash model. | Request examplesQwen3-ASR-Flash supports recordings up to 5 minutes long, accepts a public audio file URL or a local file upload as input, and can return recognition results in streaming mode. Input: audio file URLInput: Base64-encoded audio fileYou can pass in Base64-encoded data (Data URL) in the format
Input: absolute path of a local audio fileWhen you process a local audio file with the DashScope SDK, pass in the file path. Refer to the following table to build the path based on your call method and operating system.
ImportantLocal file calls are capped at 100 QPS and cannot be scaled up, so they are not suitable for production, high-concurrency, or stress-testing scenarios. For higher concurrency, upload the file to OSS and call it through a URL. Streaming outputThe model generates intermediate results step by step, and the final result is assembled from them. A non-streaming call waits for all results to be generated and then returns them at once, whereas a streaming call returns results as they are generated, which significantly reduces the time to first token. Choose the streaming parameter that matches your call method:
Python SDKJava SDKcURLThe following configuration is for the China (Beijing) region. Replace |
Response bodyrequest_id The unique identifier for this call. NoteThe parameter returned by the Java SDK is output The call result information. usage The token consumption information for this request. | |
DashScope asynchronous invocation
Process description
Unlike OpenAI-compatible mode or DashScope synchronous invocation (both of which make a single request and return the result immediately), asynchronous invocation is designed for long audio files or time-consuming tasks. It uses a two-step "submit-poll" process to prevent request timeouts caused by long waits:
-
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_idto poll the result query API. - When the task is complete, the result query API returns the final recognition result.
- The client uses the
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 Request examples. 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 encapsulate the underlying API call details and provide a more convenient programming experience.
- Submit a task: With the Python SDK, call
client.audio.asr.jobs.createto create the task, which returns a task object containing atask_id; with the Java SDK, call theasyncCall()method to submit the task. - Obtain the result: With the Python SDK, call
client.audio.asr.jobs.fetchto query the task result, or callclient.audio.asr.jobs.waitto wait for the task to finish (it automatically handles the internal polling logic until the task is complete or times out); with the Java SDK, use the task object returned in the previous step or thetask_idto call thefetch()method to retrieve the result.
- Submit a task: With the Python SDK, call
-
Use a RESTful API
Calling the RESTful API directly provides maximum flexibility.
- Submit the task. If the request is successful, the response body will contain a
task_id. - Use the
task_idfrom the previous step to retrieve the task execution result.
- Submit the task. If the request is successful, the response body will contain a
Complete example
HTTP
import com.google.gson.Gson;
import com.google.gson.annotations.SerializedName;
import okhttp3.*;
import java.io.IOException;
import java.util.concurrent.TimeUnit;
public class Main {
// The following is the configuration for the China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
private static final String API_URL_SUBMIT = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription";
// The following is the configuration for the China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
private static final String API_URL_QUERY = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/";
private static final Gson gson = new Gson();
public static void main(String[] args) {
// The API Key differs between the Singapore and Beijing regions. Get an API Key: https://help.aliyun.com/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: String apiKey = "sk-xxx"
String apiKey = System.getenv("DASHSCOPE_API_KEY");
OkHttpClient client = new OkHttpClient();
// 1. Submit the task
String payloadJson = """
{
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "{YOUR_AUDIO_URL}"
},
"parameters": {
"channel_id": [0],
"enable_itn": false,
"enable_words": true
}
}
""";
RequestBody body = RequestBody.create(payloadJson, MediaType.get("application/json; charset=utf-8"));
Request submitRequest = new Request.Builder()
.url(API_URL_SUBMIT)
.addHeader("Authorization", "Bearer " + apiKey)
.addHeader("Content-Type", "application/json")
.addHeader("X-DashScope-Async", "enable")
.post(body)
.build();
String taskId = null;
try (Response response = client.newCall(submitRequest).execute()) {
if (response.isSuccessful() && response.body() != null) {
String respBody = response.body().string();
ApiResponse apiResp = gson.fromJson(respBody, ApiResponse.class);
if (apiResp.output != null) {
taskId = apiResp.output.taskId;
System.out.println("Task submitted, task_id: " + taskId);
} else {
System.out.println("Submission response content: " + respBody);
return;
}
} else {
System.out.println("Task submission failed! HTTP code: " + response.code());
if (response.body() != null) {
System.out.println(response.body().string());
}
return;
}
} catch (IOException e) {
e.printStackTrace();
return;
}
// 2. Poll the task status
boolean finished = false;
while (!finished) {
try {
TimeUnit.SECONDS.sleep(2); // Wait 2 seconds before querying again
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
return;
}
String queryUrl = API_URL_QUERY + taskId;
Request queryRequest = new Request.Builder()
.url(queryUrl)
.addHeader("Authorization", "Bearer " + apiKey)
.addHeader("Content-Type", "application/json")
.get()
.build();
try (Response response = client.newCall(queryRequest).execute()) {
if (response.body() != null) {
String queryResponse = response.body().string();
ApiResponse apiResp = gson.fromJson(queryResponse, ApiResponse.class);
if (apiResp.output != null && apiResp.output.taskStatus != null) {
String status = apiResp.output.taskStatus;
System.out.println("Current task status: " + status);
if ("SUCCEEDED".equalsIgnoreCase(status)
|| "FAILED".equalsIgnoreCase(status)
|| "UNKNOWN".equalsIgnoreCase(status)) {
finished = true;
System.out.println("Task completed, final result: ");
System.out.println(queryResponse);
}
} else {
System.out.println("Query response content: " + queryResponse);
}
}
} catch (IOException e) {
e.printStackTrace();
return;
}
}
}
static class ApiResponse {
@SerializedName("request_id")
String requestId;
Output output;
}
static class Output {
@SerializedName("task_id")
String taskId;
@SerializedName("task_status")
String taskStatus;
}
}
import os
import time
import requests
import json
# The following is the configuration for the China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
API_URL_SUBMIT = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription"
# The following is the configuration for the China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
API_URL_QUERY_BASE = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/"
def main():
# The API Key differs between the Singapore and Beijing regions. Get an API Key: https://help.aliyun.com/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")
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
"X-DashScope-Async": "enable"
}
# 1. Submit the task
payload = {
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "{YOUR_AUDIO_URL}"
},
"parameters": {
"channel_id": [0],
# "language": "zh",
"enable_itn": False,
"enable_words": True
}
}
print("Submitting ASR transcription task...")
try:
submit_resp = requests.post(API_URL_SUBMIT, headers=headers, data=json.dumps(payload))
except requests.RequestException as e:
print(f"Failed to request task submission: {e}")
return
if submit_resp.status_code != 200:
print(f"Task submission failed! HTTP code: {submit_resp.status_code}")
print(submit_resp.text)
return
resp_data = submit_resp.json()
output = resp_data.get("output")
if not output or "task_id" not in output:
print("Abnormal submission response content:", resp_data)
return
task_id = output["task_id"]
print(f"Task submitted, task_id: {task_id}")
# 2. Poll the task status
finished = False
while not finished:
time.sleep(2) # Wait 2 seconds before querying again
query_url = API_URL_QUERY_BASE + task_id
try:
query_resp = requests.get(query_url, headers={"Authorization": f"Bearer {api_key}"})
except requests.RequestException as e:
print(f"Failed to request task query: {e}")
return
if query_resp.status_code != 200:
print(f"Task query failed! HTTP code: {query_resp.status_code}")
print(query_resp.text)
return
query_data = query_resp.json()
output = query_data.get("output")
if output and "task_status" in output:
status = output["task_status"]
print(f"Current task status: {status}")
if status.upper() in ("SUCCEEDED", "FAILED", "UNKNOWN"):
finished = True
print("Task completed. The final result is as follows:")
print(json.dumps(query_data, indent=2, ensure_ascii=False))
else:
print("Query response content:", query_data)
if __name__ == "__main__":
main()
Java SDK
import com.alibaba.dashscope.audio.qwen_asr.*;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import com.google.gson.JsonObject;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.ArrayList;
import java.util.HashMap;
public class Main {
public static void main(String[] args) {
// The following is the configuration for the China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
QwenTranscriptionParam param =
QwenTranscriptionParam.builder()
// The API Key differs between the Singapore and Beijing regions. Get an API Key: https://help.aliyun.com/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(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3-asr-flash-filetrans")
.fileUrl("{YOUR_AUDIO_URL}")
//.parameter("language", "zh")
//.parameter("channel_id", new ArrayList<String>(){{add("0");add("1");}})
.parameter("enable_itn", false)
.parameter("enable_words", true)
.build();
try {
QwenTranscription transcription = new QwenTranscription();
// Submit the task
QwenTranscriptionResult result = transcription.asyncCall(param);
System.out.println("create task result: " + result);
// Check whether the task was submitted successfully
if (result.getTaskId() == null) {
System.out.println("Error: " + result.getOutput());
return;
}
// Query the task status
result = transcription.fetch(QwenTranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
System.out.println("task status: " + result);
// Wait for the task to complete
result =
transcription.wait(
QwenTranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
System.out.println("task result: " + result);
// Get the speech recognition result
QwenTranscriptionTaskResult taskResult = result.getResult();
if (taskResult != null) {
// Get the URL of the recognition result
String transcriptionUrl = taskResult.getTranscriptionUrl();
// Get the result corresponding to the URL
HttpURLConnection connection =
(HttpURLConnection) new URL(transcriptionUrl).openConnection();
connection.setRequestMethod("GET");
connection.connect();
BufferedReader reader =
new BufferedReader(new InputStreamReader(connection.getInputStream()));
// Format and output the json result
Gson gson = new GsonBuilder().setPrettyPrinting().create();
System.out.println(gson.toJson(gson.fromJson(reader, JsonObject.class)));
}
} catch (Exception e) {
System.out.println("error: " + e);
}
}
}
Python SDK
import os
import dashscope
# run the transcription script
if __name__ == '__main__':
client = dashscope.Client(
# The API Key differs between the Singapore and Beijing regions. Get an API Key: https://help.aliyun.com/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 China (Beijing) region. When calling, replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
workspace="{WorkspaceId}",
region="cn-beijing",
)
# Submit the task
job = client.audio.asr.jobs.create(
model='qwen3-asr-flash-filetrans',
file_urls=['{YOUR_AUDIO_URL}'],
parameters={
# 'language': 'zh',
'enable_itn': False,
'enable_words': True
}
)
print(f'task_response: {job}')
print(job.task_id)
# Query the task execution result
job = client.audio.asr.jobs.fetch(job.task_id)
print(f'query_response: {job}')
# Wait for the task to complete
job = client.audio.asr.jobs.wait(job.task_id)
print(f'task_result: {job}')
Download the recognition result
After the task succeeds, the output.result.transcription_url returned by the query API points to a publicly downloadable JSON file that contains the complete recognition result. This URL is valid for 24 hours by default, so download and save it promptly.
# Replace {transcription_url} with the transcription_url value returned by the query API
curl -sS '{transcription_url}' -o transcription.json
cat transcription.json | jq .
Submit a task
URL
China (Beijing)
HTTP request address: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
base_url for SDK calls: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
Replace {WorkspaceId} with your actual workspace ID.
Singapore
HTTP request address: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
base_url for SDK calls: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1
Replace {WorkspaceId} with your actual workspace ID.
ImportantAlibaba 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.comto{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: from
dashscope-intl.aliyuncs.comto{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Request bodymodel The model name. This parameter applies only to the Qwen3-ASR-Flash-Filetrans model. input parameters | cURLJavaFor SDK examples, see Request examples. PythonFor SDK examples, see Request examples. |
Response bodyrequest_id The unique identifier for this call. output The call result information. | |
Get the task execution result
URL
China (Beijing)
HTTP request address: GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
base_url for SDK calls: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
Replace {WorkspaceId} with your actual workspace ID.
Singapore
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/v1
Replace {WorkspaceId} with your actual workspace ID.
ImportantAlibaba 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.comto{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: from
dashscope-intl.aliyuncs.comto{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Request bodytask_id The task ID. Pass the task_id from the response of the Submit a task operation to query the speech recognition result. | cURLJavaFor SDK examples, see Request examples. PythonFor SDK examples, see Request examples. |
Response bodyrequest_id The unique identifier for this call. output The call result information. | |
Description of asynchronous call resultsfile_url The URL of the recognized audio file. audio_info Information about the recognized audio file. transcripts A list of complete recognition results. Each element corresponds to the recognized content of an audio track. | |