非即時語音辨識模型能將錄製好的音頻轉換為文本，支援多語言識別、歌唱識別、雜訊拒識、說話人分離等功能，適用於會議轉寫、通話分析、字幕產生等情境。
概述
通過非同步任務對錄製好的音視頻檔案進行批量轉寫。
-
支援上下文增強，通過配置上下文提高識別準確率（僅 fun-asr-flash-2026-06-15 模型）
-
支援自訂熱詞，通過預設詞表提升專有名詞識別準確率
-
支援說話人分離、敏感詞過濾、句子/詞語級時間戳記等可配置功能
-
支援單個時間長度不超過 12 小時、體積不超過 2GB 的音頻檔案非同步轉寫
-
支援任意採樣率，相容 aac、wav、mp3 等多種主流音視頻格式
前提條件
快速開始
Fun-ASR
音視頻檔案較大，檔案轉寫 API 採用非同步呼叫：提交任務後通過查詢介面輪詢狀態，任務完成後擷取識別結果。
cURL
使用 cURL 調用時，先提交任務擷取 task_id，再通過該 ID 查詢任務執行結果。
提交任務
以下為新加坡地區的配置，調用時請將{WorkspaceId}替換為真實的Workspace ID，各地區的配置不同。
curl -X POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-Async: enable" \
-d '{
"model": "fun-asr",
"input": {
"file_urls": [
"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"
]
},
"parameters": {
"channel_id": [0],
"language_hints": ["zh", "en"]
}
}'擷取任務執行結果
此查詢介面預設 20 QPS、最高可擴容到 100 QPS。如需更高頻次或避免輪詢限流，建議配置非同步任務回調（參見 高並發情境：使用回調替代輪詢）。
以下為新加坡地區的配置，調用時請將{WorkspaceId}替換為真實的Workspace ID，各地區的配置不同。
curl -X GET 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json"下載識別結果
任務成功後，查詢介面返回的 output.results[].transcription_url 指向公網可下載的 JSON 檔案，包含完整識別結果。該 URL 預設在 24 小時內有效，請及時下載並落盤儲存。
# 將 {transcription_url} 替換為查詢介面返回的 transcription_url 值
curl -sS '{transcription_url}' -o transcription.json
cat transcription.json | jq .Python
from http import HTTPStatus
from dashscope.audio.asr import Transcription
from urllib import request
import dashscope
import os
import json
# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
task_response = Transcription.async_call(
model='fun-asr',
file_urls=['https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav'],
language_hints=['zh', 'en'] # language_hints為選擇性參數，用於指定待識別音訊語言代碼。取值範圍請參見API參考文檔。
)
transcription_response = Transcription.wait(task=task_response.output.task_id)
if transcription_response.status_code == HTTPStatus.OK:
for transcription in transcription_response.output['results']:
if transcription['subtask_status'] == 'SUCCEEDED':
url = transcription['transcription_url']
result = json.loads(request.urlopen(url).read().decode('utf8'))
print(json.dumps(result, indent=4,
ensure_ascii=False))
else:
print('transcription failed!')
print(transcription)
else:
print('Error: ', transcription_response.output.message)Java
import com.alibaba.dashscope.audio.asr.transcription.*;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.*;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Arrays;
import java.util.List;
public class Main {
public static void main(String[] args) {
// 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
// 建立轉寫請求參數。
TranscriptionParam param =
TranscriptionParam.builder()
// 新加坡和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：.apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("fun-asr")
// language_hints為選擇性參數，用於指定待識別音訊語言代碼。取值範圍請參見API參考文檔。
.parameter("language_hints", new String[]{"zh", "en"})
.fileUrls(
Arrays.asList(
"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_female2.wav"))
.build();
try {
Transcription transcription = new Transcription();
// 提交轉寫請求
TranscriptionResult result = transcription.asyncCall(param);
System.out.println("RequestId: " + result.getRequestId());
// 檢查任務是否提交成功
if (result.getTaskId() == null) {
System.out.println("Error: " + result.getOutput());
System.exit(1);
}
// 阻塞等待任務完成並擷取結果
result = transcription.wait(
TranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
// 擷取轉寫結果
List<TranscriptionTaskResult> taskResultList = result.getResults();
if (taskResultList != null && taskResultList.size() > 0) {
for (TranscriptionTaskResult taskResult : taskResultList) {
String transcriptionUrl = taskResult.getTranscriptionUrl();
HttpURLConnection connection =
(HttpURLConnection) new URL(transcriptionUrl).openConnection();
connection.setRequestMethod("GET");
connection.connect();
BufferedReader reader =
new BufferedReader(new InputStreamReader(connection.getInputStream()));
Gson gson = new GsonBuilder().setPrettyPrinting().create();
JsonElement jsonResult = gson.fromJson(reader, JsonObject.class);
System.out.println(gson.toJson(jsonResult));
}
}
} catch (Exception e) {
System.out.println("error: " + e);
}
System.exit(0);
}
}Fun-ASR-Flash
fun-asr-flash-2026-06-15 支援同步調用，適用於 5 分鐘以內的音頻檔案，可流式或非流式返回識別結果。
以下為新加坡地區的配置，調用時請將{WorkspaceId}替換為真實的Workspace ID，各地區的配置不同。新加坡地區和北京地區的API Key不同。
curl --location --request POST 'https://{WorkspaceId}.ap-southeast-1.maas.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"
}
}'注意：fun-asr-flash-2026-06-15 模型通過 DashScope 同步調用介面（multimodal-generation 端點）返回的響應結構與標準 DashScope 多模態介面格式不同。實際返回結構為：
{
"output": {
"output": {
"sentence": {
"text": "識別常值內容"
}
},
"text": "Hello World，這裡是阿里巴巴語音實驗室。"
},
"request_id": "..."
}其中 output.output.sentence.text 和頂層 output.text 為識別文字欄位，無 choices 欄位。請據此解析響應。
Qwen3-ASR-Flash-Filetrans
Qwen3-ASR-Flash-Filetrans 專為音頻檔案非同步轉寫設計，支援最長 12 小時錄音；僅接受公網音頻檔案 URL（不支援本地檔案上傳），任務完成後一次性返回全部識別結果。
cURL
使用 cURL 調用時，先提交任務擷取 task_id，再通過該 ID 查詢任務執行結果。
提交任務
以下為新加坡地區的配置，調用時請將{WorkspaceId}替換為真實的Workspace ID，各地區的配置不同。
curl -X POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-Async: enable" \
-d '{
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
},
"parameters": {
"channel_id":[
0
],
"enable_itn": false,
"enable_words": true
}
}'擷取任務執行結果
此查詢介面預設 20 QPS、最高可擴容到 100 QPS。如需更高頻次或避免輪詢限流，建議配置非同步任務回調（參見 高並發情境：使用回調替代輪詢）。
以下為新加坡地區的配置，調用時請將{WorkspaceId}替換為真實的Workspace ID，各地區的配置不同。
curl -X GET 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json"下載識別結果
任務成功後，查詢介面返回的 output.result.transcription_url 指向公網可下載的 JSON 檔案，包含完整識別結果。該 URL 預設在 24 小時內有效，請及時下載並落盤儲存。
# 將 {transcription_url} 替換為查詢介面返回的 transcription_url 值
curl -sS '{transcription_url}' -o transcription.json
cat transcription.json | jq .完整樣本
Java
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 {
// 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
private static final String API_URL_SUBMIT = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription";
// 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
private static final String API_URL_QUERY = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/";
private static final Gson gson = new Gson();
public static void main(String[] args) {
// 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：String apiKey = "sk-xxx"
String apiKey = System.getenv("DASHSCOPE_API_KEY");
OkHttpClient client = new OkHttpClient();
// 1. 提交任務
/*String payloadJson = """
{
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
},
"parameters": {
"channel_id": [0],
"enable_itn": false,
"language": "zh"
}
}
""";*/
String payloadJson = """
{
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
},
"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_id: " + taskId);
} else {
System.out.println("提交返回內容: " + respBody);
return;
}
} else {
System.out.println("任務提交失敗! HTTP code: " + response.code());
if (response.body() != null) {
System.out.println(response.body().string());
}
return;
}
} catch (IOException e) {
e.printStackTrace();
return;
}
// 2. 輪詢任務狀態
boolean finished = false;
while (!finished) {
try {
TimeUnit.SECONDS.sleep(2); // 等待 2 秒再查詢
} 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("X-DashScope-Async", "enable")
.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("當前任務狀態: " + status);
if ("SUCCEEDED".equalsIgnoreCase(status)
|| "FAILED".equalsIgnoreCase(status)
|| "UNKNOWN".equalsIgnoreCase(status)) {
finished = true;
System.out.println("任務完成，最終結果: ");
System.out.println(queryResponse);
}
} else {
System.out.println("查詢返回內容: " + 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;
}
}Python
import os
import time
import requests
import json
# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
API_URL_SUBMIT = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription"
# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
API_URL_QUERY_BASE = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/"
def main():
# 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用阿里雲百鍊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. 提交任務
payload = {
"model": "qwen3-asr-flash-filetrans",
"input": {
"file_url": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
},
"parameters": {
"channel_id": [0],
# "language": "zh",
"enable_itn": False,
"enable_words": True
}
}
print("提交 ASR 轉寫任務...")
try:
submit_resp = requests.post(API_URL_SUBMIT, headers=headers, data=json.dumps(payload))
except requests.RequestException as e:
print(f"請求提交任務失敗: {e}")
return
if submit_resp.status_code != 200:
print(f"任務提交失敗! 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("提交返回內容異常:", resp_data)
return
task_id = output["task_id"]
print(f"任務已提交，task_id: {task_id}")
# 2. 輪詢任務狀態
finished = False
while not finished:
time.sleep(2) # 等待 2 秒再查詢
query_url = API_URL_QUERY_BASE + task_id
try:
query_resp = requests.get(query_url, headers=headers)
except requests.RequestException as e:
print(f"請求查詢任務失敗: {e}")
return
if query_resp.status_code != 200:
print(f"查詢任務失敗! 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"當前任務狀態: {status}")
if status.upper() in ("SUCCEEDED", "FAILED", "UNKNOWN"):
finished = True
print("任務完成，最終結果如下：")
print(json.dumps(query_data, indent=2, ensure_ascii=False))
else:
print("查詢返回內容:", 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) {
// 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
QwenTranscriptionParam param =
QwenTranscriptionParam.builder()
// 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：.apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen3-asr-flash-filetrans")
.fileUrl("https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_example_1.wav")
//.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();
// 提交任務
QwenTranscriptionResult result = transcription.asyncCall(param);
System.out.println("create task result: " + result);
// 檢查任務是否提交成功
if (result.getTaskId() == null) {
System.out.println("Error: " + result.getOutput());
return;
}
// 查詢任務狀態
result = transcription.fetch(QwenTranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
System.out.println("task status: " + result);
// 等待任務完成
result =
transcription.wait(
QwenTranscriptionQueryParam.FromTranscriptionParam(param, result.getTaskId()));
System.out.println("task result: " + result);
// 擷取語音辨識結果
QwenTranscriptionTaskResult taskResult = result.getResult();
if (taskResult != null) {
// 擷取識別結果的url
String transcriptionUrl = taskResult.getTranscriptionUrl();
// 擷取url內對應的結果
HttpURLConnection connection =
(HttpURLConnection) new URL(transcriptionUrl).openConnection();
connection.setRequestMethod("GET");
connection.connect();
BufferedReader reader =
new BufferedReader(new InputStreamReader(connection.getInputStream()));
// 格式化輸出json結果
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 json
import os
import sys
from http import HTTPStatus
import dashscope
from dashscope.audio.qwen_asr import QwenTranscription
from dashscope.api_entities.dashscope_response import TranscriptionResponse
# run the transcription script
if __name__ == '__main__':
# 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
task_response = QwenTranscription.async_call(
model='qwen3-asr-flash-filetrans',
file_url='https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/sensevoice/rich_text_example_1.wav',
#language="",
enable_itn=False,
enable_words=True
)
print(f'task_response: {task_response}')
print(task_response.output.task_id)
query_response = QwenTranscription.fetch(task=task_response.output.task_id)
print(f'query_response: {query_response}')
task_result = QwenTranscription.wait(task=task_response.output.task_id)
print(f'task_result: {task_result}')Qwen3-ASR-Flash
Qwen3-ASR-Flash 支援最長 5 分鐘錄音，輸入支援公網音頻檔案 URL 或本地檔案上傳，可流式返回識別結果。
輸入內容：音頻檔案URL
Python SDK
import os
import dashscope
# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
messages = [
{"role": "user", "content": [{"audio": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"}]}
]
response = dashscope.MultiModalConversation.call(
# 新加坡/美國地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：api_key = "sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 若使用美國地區的模型，需在模型後面加上“-us”尾碼，例如qwen3-asr-flash-us
model="qwen3-asr-flash",
messages=messages,
result_format="message",
asr_options={
#"language": "zh", # 可選，若已知音訊語種，可通過該參數指定待識別語種，以提升識別準確率
"enable_itn":False
}
)
print(response)Java SDK
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
public static void simpleMultiModalConversationCall()
throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("audio", "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3")))
.build();
Map<String, Object> asrOptions = new HashMap<>();
asrOptions.put("enable_itn", false);
// asrOptions.put("language", "zh"); // 可選，若已知音訊語種，可通過該參數指定待識別語種，以提升識別準確率
MultiModalConversationParam param = MultiModalConversationParam.builder()
// 新加坡/美國地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：.apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
// 若使用美國地區的模型，需在模型後面加上“-us”尾碼，例如qwen3-asr-flash-us
.model("qwen3-asr-flash")
.message(userMessage)
.parameter("asr_options", asrOptions)
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
// 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}cURL
以下為新加坡地區的配置，調用時請將{WorkspaceId}替換為真實的Workspace ID，各地區的配置不同。
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": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
}
],
"role": "user"
}
]
},
"parameters": {
"asr_options": {
"enable_itn": false
}
}
}'輸入內容：Base64編碼的音頻檔案
可輸入Base64編碼資料（Data URL），格式為：data:<mediatype>;base64,<data>。
-
<mediatype>：MIME類型因音頻格式而異，例如：
-
WAV：
audio/wav -
MP3：
audio/mpeg
-
-
<data>：音頻轉成的Base64編碼的字串Base64編碼會增大體積，請控制原檔案大小，確保編碼後仍符合輸入音頻大小限制（10MB）
-
樣本：
data:audio/wav;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4LjI5LjEwMAAAAAAAAAAAAAAA//PAxABQ/BXRbMPe4IQAhl9
Python SDK
樣本中用到的音頻檔案為：welcome.mp3。
import base64
import dashscope
import os
import pathlib
# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# 請替換為實際的音頻檔案路徑
file_path = "welcome.mp3"
# 請替換為實際的音頻檔案MIME類型
audio_mime_type = "audio/mpeg"
file_path_obj = pathlib.Path(file_path)
if not file_path_obj.exists():
raise FileNotFoundError(f"音頻檔案不存在: {file_path}")
base64_str = base64.b64encode(file_path_obj.read_bytes()).decode()
data_uri = f"data:{audio_mime_type};base64,{base64_str}"
messages = [
{"role": "user", "content": [{"audio": data_uri}]}
]
response = dashscope.MultiModalConversation.call(
# 新加坡/美國和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：api_key = "sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 若使用美國地區的模型，需在模型後面加上“-us”尾碼，例如qwen3-asr-flash-us
model="qwen3-asr-flash",
messages=messages,
result_format="message",
asr_options={
# "language": "zh", # 可選，若已知音訊語種，可通過該參數指定待識別語種，以提升識別準確率
"enable_itn":False
}
)
print(response)Java SDK
樣本中用到的音頻檔案為：welcome.mp3。
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.*;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
// 請替換為實際的音頻檔案路徑
private static final String AUDIO_FILE = "welcome.mp3";
// 請替換為實際的音頻檔案MIME類型
private static final String AUDIO_MIME_TYPE = "audio/mpeg";
public static void simpleMultiModalConversationCall()
throws ApiException, NoApiKeyException, UploadFileException, IOException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("audio", toDataUrl())))
.build();
Map<String, Object> asrOptions = new HashMap<>();
asrOptions.put("enable_itn", false);
// asrOptions.put("language", "zh"); // 可選，若已知音訊語種，可通過該參數指定待識別語種，以提升識別準確率
MultiModalConversationParam param = MultiModalConversationParam.builder()
// 新加坡/美國和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：.apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
// 若使用美國地區的模型，需在模型後面加上“-us”尾碼，例如qwen3-asr-flash-us
.model("qwen3-asr-flash")
.message(userMessage)
.parameter("asr_options", asrOptions)
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
// 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException | IOException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
// 產生 data URI
public static String toDataUrl() throws IOException {
byte[] bytes = Files.readAllBytes(Paths.get(AUDIO_FILE));
String encoded = Base64.getEncoder().encodeToString(bytes);
return "data:" + AUDIO_MIME_TYPE + ";base64," + encoded;
}
}輸入內容：本地音頻檔案絕對路徑
使用 DashScope SDK 處理本地音頻檔案時需傳入檔案路徑。請參考下表，結合調用方式與作業系統建立對應路徑。
|
系統 |
SDK |
傳入的檔案路徑 |
樣本 |
|
Linux或macOS系統 |
Python SDK |
file://{檔案的絕對路徑} |
file:///home/images/test.png |
|
Java SDK |
|||
|
Windows系統 |
Python SDK |
file://{檔案的絕對路徑} |
file://D:/images/test.png |
|
Java SDK |
file:///{檔案的絕對路徑} |
file:///D:/images/test.png |
本地檔案調用上限 100 QPS，不支援擴容，不適合生產環境、高並發或壓測情境；如需更高並發，請將檔案上傳至 OSS 並通過 URL 方式調用。
Python SDK
樣本中用到的音頻檔案為：welcome.mp3。
import os
import dashscope
# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
# 請用您的本地音訊絕對路徑替換 ABSOLUTE_PATH/welcome.mp3
audio_file_path = "file://ABSOLUTE_PATH/welcome.mp3"
messages = [
{"role": "user", "content": [{"audio": audio_file_path}]}
]
response = dashscope.MultiModalConversation.call(
# 新加坡/美國地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：api_key = "sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 若使用美國地區的模型，需在模型後面加上“-us”尾碼，例如qwen3-asr-flash-us
model="qwen3-asr-flash",
messages=messages,
result_format="message",
asr_options={
# "language": "zh", # 可選，若已知音訊語種，可通過該參數指定待識別語種，以提升識別準確率
"enable_itn":False
}
)
print(response)Java SDK
樣本中用到的音頻檔案為：welcome.mp3。
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
public static void simpleMultiModalConversationCall()
throws ApiException, NoApiKeyException, UploadFileException {
// 請用您本地檔案的絕對路徑替換掉ABSOLUTE_PATH/welcome.mp3
String localFilePath = "file://ABSOLUTE_PATH/welcome.mp3";
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("audio", localFilePath)))
.build();
Map<String, Object> asrOptions = new HashMap<>();
asrOptions.put("enable_itn", false);
// asrOptions.put("language", "zh"); // 可選，若已知音訊語種，可通過該參數指定待識別語種，以提升識別準確率
MultiModalConversationParam param = MultiModalConversationParam.builder()
// 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：.apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
// 若使用美國地區的模型，需在模型後面加上“-us”尾碼，例如qwen3-asr-flash-us
.model("qwen3-asr-flash")
.message(userMessage)
.parameter("asr_options", asrOptions)
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
try {
// 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}流式輸出
模型逐步產生中間結果，最終結果由其拼接而成。非流式調用需等待全部結果產生後一次性返回；流式調用邊產生邊返回，可顯著降低首字延遲。根據調用方式選擇對應的流式參數：
-
DashScope Python SDK方式：設定
stream參數為true。 -
DashScope Java SDK方式：需要通過
streamCall介面調用。 -
DashScope HTTP方式：需要在Header中指定
X-DashScope-SSE為enable。
Python SDK
import os
import dashscope
# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
messages = [
{"role": "user", "content": [{"audio": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"}]}
]
response = dashscope.MultiModalConversation.call(
# 新加坡/美國地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：api_key = "sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 若使用美國地區的模型，需在模型後面加上“-us”尾碼，例如qwen3-asr-flash-us
model="qwen3-asr-flash",
messages=messages,
result_format="message",
asr_options={
# "language": "zh", # 可選，若已知音訊語種，可通過該參數指定待識別語種，以提升識別準確率
"enable_itn":False
},
stream=True
)
for response in response:
try:
print(response["output"]["choices"][0]["message"].content[0]["text"])
except:
passJava SDK
import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import io.reactivex.Flowable;
public class Main {
public static void simpleMultiModalConversationCall()
throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalMessage userMessage = MultiModalMessage.builder()
.role(Role.USER.getValue())
.content(Arrays.asList(
Collections.singletonMap("audio", "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3")))
.build();
Map<String, Object> asrOptions = new HashMap<>();
asrOptions.put("enable_itn", false);
// asrOptions.put("language", "zh"); // 可選，若已知音訊語種，可通過該參數指定待識別語種，以提升識別準確率
MultiModalConversationParam param = MultiModalConversationParam.builder()
// 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：.apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
// 若使用美國地區的模型，需在模型後面加上“-us”尾碼，例如qwen3-asr-flash-us
.model("qwen3-asr-flash")
.message(userMessage)
.parameter("asr_options", asrOptions)
.build();
Flowable<MultiModalConversationResult> resultFlowable = conv.streamCall(param);
resultFlowable.blockingForEach(item -> {
try {
System.out.println(item.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"));
} catch (Exception e){
System.exit(0);
}
});
}
public static void main(String[] args) {
try {
// 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}cURL
以下為新加坡地區的配置，調用時請將{WorkspaceId}替換為真實的Workspace ID，各地區的配置不同。
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" \
-H "X-DashScope-SSE: enable" \
-d '{
"model": "qwen3-asr-flash",
"input": {
"messages": [
{
"content": [
{
"audio": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
}
],
"role": "user"
}
]
},
"parameters": {
"incremental_output": true,
"asr_options": {
"enable_itn": false
}
}
}'Paraformer
Paraformer範例程式碼和Fun-ASR的非同步呼叫相似，將model替換成Paraformer模型名即可。
進階功能
使用OpenAI相容API
美國地區不支援OpenAI相容模式。
僅Qwen3-ASR-Flash系列模型支援OpenAI相容方式調用。OpenAI相容方式僅允許輸入公網可訪問的音頻檔案URL，不支援輸入本地音頻檔案絕對路徑。
OpenAI Python SDK 版本應不低於1.52.0， Node.js SDK 版本應不低於 4.68.0。安裝/升級命令：
# Python
pip install -U "openai>=1.52.0"
# Node.js
npm install openai@^4.68.0asr_options非OpenAI標準參數。使用 OpenAI Python SDK 時，請通過 extra_body 傳入；使用 Node.js OpenAI SDK 時，直接將 asr_options 作為請求體的頂層參數傳入。
輸入內容：音頻檔案URL
Python SDK
from openai import OpenAI
import os
try:
client = OpenAI(
# 新加坡/美國地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：api_key = "sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
stream_enabled = False # 是否開啟流式輸出
completion = client.chat.completions.create(
model="qwen3-asr-flash",
messages=[
{
"content": [
{
"type": "input_audio",
"input_audio": {
"data": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
}
}
],
"role": "user"
}
],
stream=stream_enabled,
# stream設為False時，不能設定stream_options參數
# stream_options={"include_usage": True},
extra_body={
"asr_options": {
# "language": "zh",
"enable_itn": False
}
}
)
if stream_enabled:
full_content = ""
print("流式輸出內容為：")
for chunk in completion:
# 如果stream_options.include_usage為True，則最後一個chunk的choices欄位為空白列表，需要跳過（可以通過chunk.usage擷取 Token 使用量）
print(chunk)
if chunk.choices and chunk.choices[0].delta.content:
full_content += chunk.choices[0].delta.content
print(f"完整內容為：{full_content}")
else:
print(f"非流式輸出內容為：{completion.choices[0].message.content}")
except Exception as e:
print(f"錯誤資訊：{e}")Node.js SDK
// 運行前的準備工作:
// Windows/Mac/Linux 通用:
// 1. 確保已安裝 Node.js (建議版本 >= 14)
// 2. 運行以下命令安裝必要的依賴: npm install openai
import OpenAI from "openai";
const client = new OpenAI({
// 新加坡/美國地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：apiKey: "sk-xxx",
apiKey: process.env.DASHSCOPE_API_KEY,
// 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});
async function main() {
try {
const streamEnabled = false; // 是否開啟流式輸出
const completion = await client.chat.completions.create({
model: "qwen3-asr-flash",
messages: [
{
role: "user",
content: [
{
type: "input_audio",
input_audio: {
data: "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
}
}
]
}
],
stream: streamEnabled,
// stream設為False時，不能設定stream_options參數
// stream_options: {
// "include_usage": true
// },
asr_options: {
// language: "zh",
enable_itn: false
}
});
if (streamEnabled) {
let fullContent = "";
console.log("流式輸出內容為：");
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(`完整內容為：${fullContent}`);
} else {
console.log(`非流式輸出內容為：${completion.choices[0].message.content}`);
}
} catch (err) {
console.error(`錯誤資訊：${err}`);
}
}
main();cURL
以下為新加坡地區的配置，調用時請將{WorkspaceId}替換為真實的Workspace ID，各地區的配置不同。
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": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"
}
}
],
"role": "user"
}
],
"stream":false,
"asr_options": {
"enable_itn": false
}
}'輸入內容：Base64編碼的音頻檔案
可輸入Base64編碼資料（Data URL），格式為：data:<mediatype>;base64,<data>。
-
<mediatype>：MIME類型因音頻格式而異，例如：
-
WAV：
audio/wav -
MP3：
audio/mpeg
-
-
<data>：音頻轉成的Base64編碼的字串Base64編碼會增大體積，請控制原檔案大小，確保編碼後仍符合輸入音頻大小限制（10MB）
-
樣本：
data:audio/wav;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4LjI5LjEwMAAAAAAAAAAAAAAA//PAxABQ/BXRbMPe4IQAhl9
Python SDK
樣本中用到的音頻檔案為：welcome.mp3。
import base64
from openai import OpenAI
import os
import pathlib
try:
# 請替換為實際的音頻檔案路徑
file_path = "welcome.mp3"
# 請替換為實際的音頻檔案MIME類型
audio_mime_type = "audio/mpeg"
file_path_obj = pathlib.Path(file_path)
if not file_path_obj.exists():
raise FileNotFoundError(f"音頻檔案不存在: {file_path}")
base64_str = base64.b64encode(file_path_obj.read_bytes()).decode()
data_uri = f"data:{audio_mime_type};base64,{base64_str}"
client = OpenAI(
# 新加坡/美國和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：api_key = "sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
stream_enabled = False # 是否開啟流式輸出
completion = client.chat.completions.create(
model="qwen3-asr-flash",
messages=[
{
"content": [
{
"type": "input_audio",
"input_audio": {
"data": data_uri
}
}
],
"role": "user"
}
],
stream=stream_enabled,
# stream設為False時，不能設定stream_options參數
# stream_options={"include_usage": True},
extra_body={
"asr_options": {
# "language": "zh",
"enable_itn": False
}
}
)
if stream_enabled:
full_content = ""
print("流式輸出內容為：")
for chunk in completion:
# 如果stream_options.include_usage為True，則最後一個chunk的choices欄位為空白列表，需要跳過（可以通過chunk.usage擷取 Token 使用量）
print(chunk)
if chunk.choices and chunk.choices[0].delta.content:
full_content += chunk.choices[0].delta.content
print(f"完整內容為：{full_content}")
else:
print(f"非流式輸出內容為：{completion.choices[0].message.content}")
except Exception as e:
print(f"錯誤資訊：{e}")Node.js SDK
樣本中用到的音頻檔案為：welcome.mp3。
// 運行前的準備工作:
// Windows/Mac/Linux 通用:
// 1. 確保已安裝 Node.js (建議版本 >= 14)
// 2. 運行以下命令安裝必要的依賴: npm install openai
import OpenAI from "openai";
import { readFileSync } from 'fs';
const client = new OpenAI({
// 新加坡/美國和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
// 若沒有配置環境變數，請用阿里雲百鍊API Key將下行替換為：apiKey: "sk-xxx",
apiKey: process.env.DASHSCOPE_API_KEY,
// 以下為新加坡地區的配置，調用時請將"{WorkspaceId}"替換為真實的業務空間ID，各地區的配置不同。
baseURL: "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
});
const encodeAudioFile = (audioFilePath) => {
const audioFile = readFileSync(audioFilePath);
return audioFile.toString('base64');
};
// 請替換為實際的音頻檔案路徑
const dataUri = `data:audio/mpeg;base64,${encodeAudioFile("welcome.mp3")}`;
async function main() {
try {
const streamEnabled = false; // 是否開啟流式輸出
const completion = await client.chat.completions.create({
model: "qwen3-asr-flash",
messages: [
{
role: "user",
content: [
{
type: "input_audio",
input_audio: {
data: dataUri
}
}
]
}
],
stream: streamEnabled,
// stream設為False時，不能設定stream_options參數
// stream_options: {
// "include_usage": true
// },
asr_options: {
// language: "zh",
enable_itn: false
}
});
if (streamEnabled) {
let fullContent = "";
console.log("流式輸出內容為：");
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(`完整內容為：${fullContent}`);
} else {
console.log(`非流式輸出內容為：${completion.choices[0].message.content}`);
}
} catch (err) {
console.error(`錯誤資訊：${err}`);
}
}
main();長音頻檔案處理
非即時語音辨識支援長音頻檔案非同步轉寫，適用於會議記錄、訪談整理、通話回放等情境。
限制說明：
-
Fun-ASR / Qwen3-ASR-Flash-Filetrans / Paraformer：單個音頻檔案大小不超過 2GB，時間長度不超過 12 小時。
-
Qwen3-ASR-Flash：單個音頻檔案大小不超過 10MB，時間長度不超過 5 分鐘。對於較長音頻，請使用 Fun-ASR 或Qwen3-ASR-Flash-Filetrans。
-
啟用說話人分離時：建議音頻時間長度不超過 2 小時，否則可能導致識別失敗或逾時。詳見說話人分離。
調用方式：長音頻轉寫採用非同步任務模式，分三步：
-
提交轉寫任務，擷取
task_id。 -
通過輪詢介面查詢任務狀態（或使用 SDK 的等待方法阻塞等待）。
-
任務完成後從返回的 URL 下載識別結果 JSON。
具體程式碼範例請參見Qwen3-ASR-Flash-Filetrans的快速開始代碼。
流式輸出
Qwen3-ASR-Flash 支援流式輸出：邊識別邊返回中間結果，適用於需要即時反饋進度的情境。
Fun-ASR、Qwen3-ASR-Flash-Filetrans、Paraformer 等非同步轉寫模型不支援流式輸出，需通過任務輪詢擷取最終結果（詳見長音頻檔案處理）。
啟用方式：
-
DashScope Python SDK：設定
stream參數為True。 -
DashScope Java SDK：通過
streamCall介面調用。 -
DashScope HTTP：在 Header 中設定
X-DashScope-SSE為enable。 -
OpenAI 相容 SDK：設定
stream參數為True。
具體的流式輸出程式碼範例，請參見快速開始中Qwen3-ASR-Flash的流式輸出章節。
使用熱詞提升準確率
Fun-ASR 和 Paraformer 支援通過熱詞提升特定領域專有名詞（人名、地名、產品名等）的識別準確率。在阿里雲百鍊控制台建立熱詞表後，調用 API 時通過 vocabulary_id 參數指定該熱詞表 ID 即可。
詳細的建立和使用方法，請參見提升識別準確率。
不同 SDK 暴露上述參數的命名習慣不同（如字典 key、對象屬性、方法等），完整欄位對照請參見各 SDK 的 API 參考。
使用上下文增強提升準確率
fun-asr-flash-2026-06-15 模型支援上下文增強功能，可將對話歷史傳入 ASR 模型，顯著提升專有詞彙的轉寫準確率。詳細的使用方法和效果樣本，請參見上下文增強。
說話人分離
說話人分離可自動識別音頻中不同說話人，並在轉寫結果中為每個句子標註說話人標籤，適用於多人會議、訪談錄音等情境。
支援範圍：Fun-ASR 和 Paraformer 模型支援說話人分離功能（預設關閉），Qwen-ASR 系列暫不支援。
啟用方式：在 API 請求參數中設定 diarization_enabled 為 true。識別結果中每個句子會包含 speaker_id 欄位，標識不同說話人。
返回結構樣本（節選）：
{
"transcripts": [
{
"sentences": [
{ "begin_time": 100, "end_time": 3820, "text": "你好，我們今天討論專案進度。", "speaker_id": 0 },
{ "begin_time": 3820, "end_time": 6500, "text": "好的，我先彙報一下。", "speaker_id": 1 }
]
}
]
}不同 SDK 暴露上述欄位的命名習慣不同（如字典 key、對象屬性、方法等），完整欄位對照請參見各 SDK 的 API 參考。
啟用說話人分離功能時，建議音頻時間長度不超過 2 小時，否則可能導致識別失敗或逾時（不啟用時音頻長度限制詳見長音頻檔案處理）。說話人分離僅支援單聲道音頻。
完整欄位定義請參見API參考。
敏感詞過濾
敏感詞過濾可對識別結果中的敏感詞執行替換或移除，適用於客服質檢、內容合規、字幕審核等情境。
支援範圍：Fun-ASR 與 Paraformer 模型支援，Qwen-ASR 系列（Qwen3-ASR-Flash 與Qwen3-ASR-Flash-Filetrans）暫不支援。
預設行為：未傳入 special_word_filter 參數時，系統啟用內建的阿里雲百鍊敏感詞表，匹配的詞語會被替換為等長的 *。
自訂配置：special_word_filter 是 JSON 對象，包含三個子欄位：
-
filter_with_signed.word_list：字串數組，列出需要被替換為等長*的敏感詞。例如["測試"]，「幫我測試一下」會變成「幫我**一下」。 -
filter_with_empty.word_list：字串數組，列出需要從結果中完全移除的敏感詞。例如["開始"]，「比賽這就要開始了嗎」會變成「比賽這就要了嗎」。 -
system_reserved_filter：布爾值，預設true。是否同時啟用系統預置敏感詞表（與自訂詞表疊加生效）。
配置樣本：
{
"special_word_filter": {
"filter_with_signed": {
"word_list": ["測試"]
},
"filter_with_empty": {
"word_list": ["開始", "發生"]
},
"system_reserved_filter": true
}
}不同 SDK 暴露上述參數的命名習慣不同（如字典 key、對象屬性、方法等），完整欄位對照請參見 API參考。
情感識別
Qwen3-ASR-Flash-Filetrans 與Qwen3-ASR-Flash 模型固定開啟情感識別，無需額外配置。識別結果中會附帶說話人的情緒標籤，取值為 7 類細粒度情緒：surprised（驚訝）、neutral（平靜）、happy（愉快）、sad（悲傷）、disgusted（厭惡）、angry（憤怒）、fearful（恐懼）。
欄位路徑（因介面而異）：
-
OpenAI 相容介面（Qwen3-ASR-Flash 即時轉寫）：嵌套在
choices[].delta.annotations[].emotion（流式輸出）或choices[].message.annotations[].emotion（非流式）。 -
DashScope 同步調用介面（Qwen3-ASR-Flash）：嵌套在
output.choices[].message.annotations[].emotion。 -
DashScope 非同步任務介面（Qwen3-ASR-Flash-Filetrans 錄音檔案轉寫）：嵌套在
transcripts[].sentences[].emotion，與時間戳記、說話人等欄位並列在每個句子物件中。
返回結構樣本（DashScope 非同步任務介面節選）：
{
"transcripts": [{
"sentences": [{
"begin_time": 0,
"end_time": 1440,
"text": "歡迎使用阿里雲。",
"emotion": "neutral",
"language": "zh"
}]
}]
}不同 SDK 暴露上述欄位的命名習慣不同（如字典 key、對象屬性、方法等），完整欄位對照請參見API參考。
Fun-ASR 和 Paraformer 非即時模型暫不支援情感識別功能。如需在即時識別中使用情感識別，可參考 即時語音辨識 的對應章節。
擷取時間戳記
非即時語音辨識支援在轉寫結果中輸出時間戳記，便於字幕產生、關鍵詞高亮、音視訊剪輯等情境。Fun-ASR、Qwen3-ASR-Flash-Filetrans、Paraformer 三個非同步轉寫模型均支援，但各模型的時間戳記預設行為和控制方式不同：
-
Fun-ASR：時間戳記功能固定開啟，不可關閉。
-
Qwen3-ASR-Flash-Filetrans：僅 DashScope 非同步呼叫方式支援時間戳記，時間戳記功能固定開啟。可通過請求參數
enable_words控制時間戳記層級：設為false（預設）返回句級時間戳記，設為true返回字級時間戳記。字層級時間戳記僅支援以下語種：中文、英語、日語、韓語、德語、法語、西班牙語、意大利語、葡萄牙語、俄語，其他語種可能無法保證準確性。 -
Paraformer：時間戳記功能預設關閉，可通過請求參數
timestamp_alignment_enabled設為true開啟。
Qwen3-ASR-Flash 通過 OpenAI 相容介面調用時，輸出形態為 chat.completion，不返回時間戳記欄位。如需時間戳記，請使用Qwen3-ASR-Flash-Filetrans（非同步任務介面）。
時間戳記單位均為毫秒，分兩個層級返回：
-
句級：
sentences[].begin_time與sentences[].end_time，標識每個句子在音頻中的起止時刻。 -
字級：
sentences[].words[]數組，每個元素包含begin_time、end_time與text（該字/詞文本）。
返回結構樣本（DashScope 非同步任務介面節選）：
{
"transcripts": [{
"sentences": [{
"begin_time": 100,
"end_time": 3820,
"text": "你好，我們今天討論專案進度。",
"words": [
{ "begin_time": 100, "end_time": 596, "text": "你好" },
{ "begin_time": 596, "end_time": 844, "text": "我們" }
]
}]
}]
}音頻內時間戳記是毫秒整數（如 100），與任務級 end_time（任務完成時間，字串日期如 "2024-09-12 15:11:40.903"）不是同一欄位，請勿混淆。
不同 SDK 暴露上述欄位的命名習慣不同（如字典 key、對象屬性、方法等），完整欄位對照請參見 API參考。
應用於生產環境
將非即時語音辨識應用於生產環境時，以下最佳實務有助於提升識別效果和系統穩定性。
高並發情境：使用回調替代輪詢
非同步轉寫任務（Fun-ASR、Qwen3-ASR-Flash-Filetrans、Paraformer）通過 POST /api/v1/services/audio/asr/transcription 提交後，通常做法是周期性調用查詢介面 GET /api/v1/tasks/{task_id} 擷取結果。該查詢介面預設 20 QPS、最高可擴容至 100 QPS，在高並發批量情境下，頻繁輪詢易觸發限流。
通過事件匯流排 EventBridge 配置回調通知，任務完成時阿里雲百鍊會自動推送 dashscope:System:AsyncTaskFinish 事件至您配置的目標（HTTP/HTTPS 端點或 RocketMQ Topic），消費端收到事件後無需再調用查詢介面，從而規避因頻繁輪詢而被限流的風險。詳情請參見配置 EventBridge 回調通知。
適用模型
-
適用模型：Fun-ASR、Qwen3-ASR-Flash-Filetrans、Paraformer（均為非同步轉寫任務）。
-
不適用：Qwen3-ASR-Flash（同步/流式調用，不屬非同步任務範疇）。
回調訊息內容
三種模型的回調訊息體中 data.contain_result 均為 true，data.output_result 直接攜帶 transcription_url，消費端收到回調後即可擷取識別結果，無需再調用 GET /api/v1/tasks/{task_id}。但三個模型的結果欄位路徑與結構不同，詳見下表。
編寫消費端時請按使用的模型選擇正確路徑，不可寫死為單一路徑。失敗情境下 data.output_result.output 不再含 results/result，而是含 code 與 message 欄位，需先判斷 data.task_status 再取結果。
|
模型 |
提交參數 |
結果欄位路徑（基於回調 Body） |
usage 欄位 |
|
Fun-ASR |
|
|
|
|
Paraformer |
|
同 Fun-ASR： |
|
|
Qwen3-ASR-Flash-Filetrans |
|
|
|
注意事項
安全（HTTP/HTTPS 投遞方式）：生產環境必須校正回調要求標頭中的 X-Eventbridge-Signature* 數列欄位後再消費，否則任意外部 IP 都可偽造 AsyncTaskFinish 事件，注入虛假識別結果。建議同時為接收端設定至少 5 秒的接收逾時。RocketMQ 投遞方式無訊息級簽名，安全性由 RocketMQ 鑒權機制保證。
投遞延遲：從任務結束（end_time）到投遞目標（HTTP/HTTPS 端點或 RocketMQ Topic）收到訊息，通常約 1–90 秒，具體延遲受 EventBridge 即時負載影響。
等冪性：同一事件可能因重試而被投遞多次。消費端需實現等冪處理，建議以 CloudEvents data.id 或 data.task_id 作為去重鍵。
生產環境建議
-
檔案託管：將音頻檔案上傳至阿里雲 OSS，通過 URL 方式調用，避免使用本地檔案上傳（本地檔案調用上限 100 QPS，不支援擴容）。
-
非同步輪詢：長音頻轉寫採用非同步模式，建議設定合理的輪詢間隔（如 2~5 秒），避免頻繁查詢消耗配額。如需突破 20–100 QPS 查詢上限，可改用事件回調通知，詳見高並發情境：使用回調替代輪詢。
-
錯誤處理：實現完善的重試機制；網路逾時或服務端臨時錯誤（5xx）按指數退避策略重試。
-
降噪處理：雜訊較大的音頻建議先用 FFmpeg 等工具預先處理後再提交識別。
-
模型選擇：根據音頻時間長度選擇合適的模型。5 分鐘以內的短音頻使用Qwen3-ASR-Flash，超過 5 分鐘的長音頻使用 Fun-ASR 或Qwen3-ASR-Flash-Filetrans。
支援的模型與地區
新加坡
調用以下模型時，請選擇新加坡地區的API Key：
-
Fun-ASR：fun-asr（穩定版，當前等同fun-asr-2025-11-07）、fun-asr-2025-11-07（快照版）、fun-asr-2025-08-25（快照版）、fun-asr-mtl（穩定版，當前等同fun-asr-mtl-2025-08-25）、fun-asr-mtl-2025-08-25（快照版）
-
Fun-ASR-Flash：fun-asr-flash-2026-06-15
-
Qwen3-ASR-Flash-Filetrans：qwen3-asr-flash-filetrans（穩定版，當前等同qwen3-asr-flash-filetrans-2025-11-17）、qwen3-asr-flash-filetrans-2025-11-17（快照版）
-
Qwen3-ASR-Flash：qwen3-asr-flash（穩定版，當前等同qwen3-asr-flash-2025-09-08）、qwen3-asr-flash-2026-02-10（最新快照版）、qwen3-asr-flash-2025-09-08（快照版）
美國（維吉尼亞）
調用以下模型時，請選擇美國地區的API Key：
Qwen3-ASR-Flash：qwen3-asr-flash-us（穩定版，當前等同qwen3-asr-flash-2025-09-08-us）、qwen3-asr-flash-2025-09-08-us（快照版）
華北2（北京）
調用以下模型時，請選擇北京地區的API Key：
-
Fun-ASR：fun-asr（穩定版，當前等同fun-asr-2025-11-07）、fun-asr-2025-11-07（快照版）、fun-asr-2025-08-25（快照版）、fun-asr-mtl（穩定版，當前等同fun-asr-mtl-2025-08-25）、fun-asr-mtl-2025-08-25（快照版）
-
Fun-ASR-Flash：fun-asr-flash-2026-06-15
-
Qwen3-ASR-Flash-Filetrans：qwen3-asr-flash-filetrans（穩定版，當前等同qwen3-asr-flash-filetrans-2025-11-17）、qwen3-asr-flash-filetrans-2025-11-17（快照版）
-
Qwen3-ASR-Flash：qwen3-asr-flash（穩定版，當前等同qwen3-asr-flash-2025-09-08）、qwen3-asr-flash-2026-02-10（最新快照版）、qwen3-asr-flash-2025-09-08（快照版）
-
Paraformer：paraformer-v2、paraformer-8k-v2
API參考
常見問題
Q：如何為API提供公網可訪問的音頻URL？
推薦使用阿里雲Object Storage Service，它提供了高可用、高可靠的儲存服務，並且可以方便地產生公網訪問URL。
在公網環境下驗證產生的 URL 可正常訪問：可在瀏覽器或通過 curl 命令訪問該 URL，確保音頻檔案能夠成功下載或播放（HTTP狀態代碼為200）。
Q：如何檢查音頻格式是否符合要求？
可以使用開源工具ffprobe快速擷取音訊詳細資料：
# 查詢音訊容器格式(format_name)、編碼(codec_name)、採樣率(sample_rate)、聲道數(channels)
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 your_audio_file.mp3Q：如何處理音頻以滿足模型要求？
可以使用開源工具FFmpeg對音頻進行裁剪或格式轉換：
-
音頻裁剪：從長音頻中截取片段
# -i: 輸入檔案 # -ss 00:01:30: 設定裁剪的起始時間 (從1分30秒開始) # -t 00:02:00: 設定裁剪的持續時間長度 (裁剪2分鐘) # -c copy: 直接複製音頻流，不重新編碼，速度快 # output_clip.wav: 輸出檔案 ffmpeg -i long_audio.wav -ss 00:01:30 -t 00:02:00 -c copy output_clip.wav -
格式轉換
例如，將任意音頻轉換為16kHz、16-bit、單聲道WAV檔案
# -i: 輸入檔案 # -ac 1: 設定聲道數為1 (單聲道) # -ar 16000: 設定採樣率為16000Hz (16kHz) # -sample_fmt s16: 設定採樣格式為16-bit signed integer PCM # output.wav: 輸出檔案 ffmpeg -i input.mp3 -ac 1 -ar 16000 -sample_fmt s16 output.wav
Q：如何提升識別準確率？
以下因素影響識別準確率，請逐項排查並針對性最佳化。
主要影響因素：
-
聲音品質：錄音裝置品質、採樣率及環境雜訊直接影響音頻清晰度，高品質音頻輸入是準確識別的基礎
-
說話人特徵：音調、語速、口音和方言差異（尤其少見方言或重口音）增加識別難度
-
語言和詞彙：多語言混合、專業術語或俚語增加識別難度，可通過配置熱詞最佳化特定領域術語的準確率
最佳化方法：
-
最佳化音頻品質：使用高效能麥克風，按推薦採樣率錄音，盡量減少環境雜訊與回聲
-
適配說話人：對於口音較重或方言明顯的音頻，選用支援對應方言的模型
-
配置熱詞：為專業術語、專有名詞等設定熱詞