非实时语音识别模型能将录制好的音频转换为文本，支持多语言识别、歌唱识别、噪声拒识、说话人分离等功能，适用于会议转写、通话分析、字幕生成等场景。
概述
通过异步任务对录制好的音视频文件进行批量转写。
-
支持说话人分离、敏感词过滤、句子/词语级时间戳、热词增强等可配置功能
-
支持单个时长不超过 12 小时、体积不超过 2GB 的音频文件异步转写
-
支持任意采样率，兼容 aac、wav、mp3 等多种主流音视频格式
前提条件
快速开始
Fun-ASR
音视频文件较大，文件转写 API 采用异步调用：提交任务后通过查询接口轮询状态，任务完成后获取识别结果。
Python
from http import HTTPStatus
from dashscope.audio.asr import Transcription
from urllib import request
import dashscope
import os
import json
# 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope.aliyuncs.com/api/v1'
# 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/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',
'https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.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) {
// 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
// 创建转写请求参数。
TranscriptionParam param =
TranscriptionParam.builder()
// 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/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",
"https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/paraformer/hello_world_male2.wav"))
.build();
try {
Transcription transcription = new Transcription();
// 提交转写请求
TranscriptionResult result = transcription.asyncCall(param);
System.out.println("RequestId: " + result.getRequestId());
// 阻塞等待任务完成并获取结果
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);
}
}千问3-ASR-Flash-Filetrans
千问3-ASR-Flash-Filetrans 专为音频文件异步转写设计，支持最长 12 小时录音；仅接受公网音频文件 URL（不支持本地文件上传），任务完成后一次性返回全部识别结果。
cURL
使用 cURL 调用时，先提交任务获取 task_id，再通过该 ID 查询任务执行结果。
提交任务
以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/transcription。
curl -X POST 'https://dashscope.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
}
}'获取任务执行结果
以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}。注意将 {task_id} 替换为待查询任务ID。
curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "X-DashScope-Async: enable" \
-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 {
// 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/transcription
private static final String API_URL_SUBMIT = "https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription";
// 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1/tasks/
private static final String API_URL_QUERY = "https://dashscope.aliyuncs.com/api/v1/tasks/";
private static final Gson gson = new Gson();
public static void main(String[] args) {
// 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/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
# 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/transcription
API_URL_SUBMIT = "https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription"
# 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1/tasks/
API_URL_QUERY_BASE = "https://dashscope.aliyuncs.com/api/v1/tasks/"
def main():
# 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/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) {
// 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
QwenTranscriptionParam param =
QwenTranscriptionParam.builder()
// 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/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);
// 查询任务状态
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://help.aliyun.com/zh/model-studio/get-api-key
# 若没有配置环境变量，请用百炼API Key将下行替换为：dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
# 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope.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}')千问3-ASR-Flash
千问3-ASR-Flash 支持最长 5 分钟录音，输入支持公网音频文件 URL 或本地文件上传，可流式返回识别结果。
输入内容：音频文件URL
Python SDK
import os
import dashscope
# 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1，若使用美国地域的模型，需将url替换为：https://dashscope-us.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope.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://help.aliyun.com/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://help.aliyun.com/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 {
// 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1，若使用美国地域的模型，需将url替换为：https://dashscope-us.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}cURL
以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation，若使用美国地域的模型，需将url替换为：https://dashscope-us.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation。
curl -X POST "https://dashscope.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": [
{
"text": ""
}
],
"role": "system"
},
{
"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
# 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1，若使用美国地域的模型，需将url替换为：https://dashscope-us.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope.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://help.aliyun.com/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://help.aliyun.com/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 {
// 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1，若使用美国地域的模型，需将url替换为：https://dashscope-us.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope.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
# 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1，若使用美国地域的模型，需将url替换为：https://dashscope-us.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope.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://help.aliyun.com/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://help.aliyun.com/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 {
// 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1，若使用美国地域的模型，需将url替换为：https://dashscope-us.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope.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
# 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1，若使用美国地域的模型，需将url替换为：https://dashscope-us.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope.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://help.aliyun.com/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://help.aliyun.com/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 {
// 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1，若使用美国地域的模型，需将url替换为：https://dashscope-us.aliyuncs.com/api/v1
Constants.baseHttpApiUrl = "https://dashscope.aliyuncs.com/api/v1";
simpleMultiModalConversationCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}cURL
以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation，若使用美国地域的模型，需将url替换为：https://dashscope-us.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation。
curl -X POST "https://dashscope.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": [
{
"text": ""
}
],
"role": "system"
},
{
"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兼容模式。
仅千问3-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 SDK，请通过extra_body传入。
输入内容：音频文件URL
Python SDK
from openai import OpenAI
import os
try:
client = OpenAI(
# 新加坡和北京地域的API Key不同。获取API Key：https://help.aliyun.com/zh/model-studio/get-api-key
# 若没有配置环境变量，请用百炼API Key将下行替换为：api_key = "sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
base_url="https://dashscope.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://help.aliyun.com/zh/model-studio/get-api-key
// 若没有配置环境变量，请用百炼API Key将下行替换为：apiKey: "sk-xxx",
apiKey: process.env.DASHSCOPE_API_KEY,
// 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
baseURL: "https://dashscope.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
// },
extra_body: {
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
以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions。
curl -X POST 'https://dashscope.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://help.aliyun.com/zh/model-studio/get-api-key
# 若没有配置环境变量，请用百炼API Key将下行替换为：api_key = "sk-xxx",
api_key=os.getenv("DASHSCOPE_API_KEY"),
# 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
base_url="https://dashscope.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://help.aliyun.com/zh/model-studio/get-api-key
// 若没有配置环境变量，请用百炼API Key将下行替换为：apiKey: "sk-xxx",
apiKey: process.env.DASHSCOPE_API_KEY,
// 以下为北京地域url，若使用新加坡地域的模型，需将url替换为：https://dashscope-intl.aliyuncs.com/compatible-mode/v1
baseURL: "https://dashscope.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
// },
extra_body: {
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();长音频文件处理
非实时语音识别支持长音频文件异步转写，适用于会议记录、访谈整理、通话回放等场景。
限制说明：
-
千问3-ASR-Flash-Filetrans / Fun-ASR / Paraformer：单个音频文件大小不超过 2GB，时长不超过 12 小时。
-
千问3-ASR-Flash：单个音频文件大小不超过 10MB，时长不超过 5 分钟。对于较长音频，请使用千问3-ASR-Flash-Filetrans 或 Fun-ASR。
-
启用说话人分离时：建议音频时长不超过 2 小时，否则可能导致识别失败或超时。详见说话人分离。
调用方式：长音频转写采用异步任务模式，分三步：
-
提交转写任务，获取
task_id。 -
通过轮询接口查询任务状态（或使用 SDK 的等待方法阻塞等待）。
-
任务完成后从返回的 URL 下载识别结果 JSON。
具体代码示例请参见千问3-ASR-Flash-Filetrans的快速开始代码。
流式输出
千问3-ASR-Flash 支持流式输出：边识别边返回中间结果，适用于需要实时反馈进度的场景。
Fun-ASR、Paraformer、千问3-ASR-Flash-Filetrans 等异步转写模型不支持流式输出，需通过任务轮询获取最终结果（详见长音频文件处理）。
启用方式：
-
DashScope Python SDK：设置
stream参数为True。 -
DashScope Java SDK：通过
streamCall接口调用。 -
DashScope HTTP：在 Header 中设置
X-DashScope-SSE为enable。 -
OpenAI 兼容 SDK：设置
stream参数为True。
具体的流式输出代码示例，请参见快速开始中千问3-ASR-Flash的流式输出章节。
使用热词提升准确率
Fun-ASR 和 Paraformer 支持通过热词提升特定领域专有名词（人名、地名、产品名等）的识别准确率。在百炼控制台创建热词表后，调用 API 时通过 vocabulary_id 参数指定该热词表 ID 即可。
详细的创建和使用方法，请参见自定义热词。
不同 SDK 暴露上述参数的命名习惯不同（如字典 key、对象属性、方法等），完整字段对照请参见各 SDK 的 API 参考。
说话人分离
说话人分离可自动识别音频中不同说话人，并在转写结果中为每个句子标注说话人标签，适用于多人会议、访谈录音等场景。
支持范围：Fun-ASR 和 Paraformer 模型支持说话人分离功能（默认关闭），千问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 系列（千问3-ASR-Flash 与千问3-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参考。
情感识别
千问3-ASR-Flash-Filetrans 与千问3-ASR-Flash 模型固定开启情感识别，无需额外配置。识别结果中会附带说话人的情绪标签，取值为 7 类细粒度情绪：surprised（惊讶）、neutral（平静）、happy（愉快）、sad（悲伤）、disgusted（厌恶）、angry（愤怒）、fearful（恐惧）。
字段路径（因接口而异）：
-
OpenAI 兼容接口（千问3-ASR-Flash 实时转写）：嵌套在
choices[].delta.annotations[].emotion（流式输出）或choices[].message.annotations[].emotion（非流式）。 -
DashScope 同步调用接口（千问3-ASR-Flash）：嵌套在
output.choices[].message.annotations[].emotion。 -
DashScope 异步任务接口（千问3-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、Paraformer、千问3-ASR-Flash-Filetrans 三个异步转写模型均支持，但各模型的时间戳默认行为和控制方式不同：
-
千问3-ASR-Flash-Filetrans：仅 DashScope 异步调用方式支持时间戳，时间戳功能固定开启。可通过请求参数
enable_words控制时间戳级别：设为false（默认）返回句级时间戳，设为true返回字级时间戳。字级别时间戳仅支持以下语种：中文、英语、日语、韩语、德语、法语、西班牙语、意大利语、葡萄牙语、俄语，其他语种可能无法保证准确性。 -
Fun-ASR：时间戳功能固定开启，不可关闭。
-
Paraformer：时间戳功能默认关闭，可通过请求参数
timestamp_alignment_enabled设为true开启。
重要
千问3-ASR-Flash 通过 OpenAI 兼容接口调用时，输出形态为 chat.completion，不返回时间戳字段。如需时间戳，请使用千问3-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参考。
应用于生产环境
将非实时语音识别应用于生产环境时，以下最佳实践有助于提升识别效果和系统稳定性。
生产环境建议
-
文件托管：将音频文件上传至阿里云 OSS，通过 URL 方式调用，避免使用本地文件上传（本地文件调用上限 100 QPS，不支持扩容）。
-
异步轮询：长音频转写采用异步模式，建议设置合理的轮询间隔（如 2~5 秒），避免频繁查询消耗配额。
-
错误处理：实现完善的重试机制；网络超时或服务端临时错误（5xx）按指数退避策略重试。
-
降噪处理：噪声较大的音频建议先用 FFmpeg 等工具预处理后再提交识别。
-
模型选择：根据音频时长选择合适的模型。5 分钟以内的短音频使用千问3-ASR-Flash，超过 5 分钟的长音频使用千问3-ASR-Flash-Filetrans 或 Fun-ASR。
适用范围
不同服务部署范围支持的模型不同：
中国内地
服务部署范围为中国内地时，模型推理计算资源仅限于中国内地；静态数据存储于您所选的地域。该部署范围支持的地域：华北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（快照版）
-
千问3-ASR-Flash-Filetrans：qwen3-asr-flash-filetrans（稳定版，当前等同qwen3-asr-flash-filetrans-2025-11-17）、qwen3-asr-flash-filetrans-2025-11-17（快照版）
-
千问3-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、paraformer-v1、paraformer-8k-v1、paraformer-mtl-v1
国际
服务部署范围为国际时，模型推理计算资源在全球范围内动态调度（不含中国内地）；静态数据存储于您所选的地域。该部署范围支持的地域：新加坡。
调用以下模型时，请选择新加坡地域的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（快照版）
-
千问3-ASR-Flash-Filetrans：qwen3-asr-flash-filetrans（稳定版，当前等同qwen3-asr-flash-filetrans-2025-11-17）、qwen3-asr-flash-filetrans-2025-11-17（快照版）
-
千问3-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：
千问3-ASR-Flash：qwen3-asr-flash-us（稳定版，当前等同qwen3-asr-flash-2025-09-08-us）、qwen3-asr-flash-2025-09-08-us（快照版）
API参考
模型应用上架及备案
参见应用合规备案。
常见问题
Q：如何为API提供公网可访问的音频URL？
推荐使用阿里云对象存储OSS，它提供了高可用、高可靠的存储服务，并且可以方便地生成公网访问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：如何提升识别准确率？
以下因素影响识别准确率，请逐项排查并针对性优化。
主要影响因素：
-
声音质量：录音设备品质、采样率及环境噪声直接影响音频清晰度，高质量音频输入是准确识别的基础
-
说话人特征：音调、语速、口音和方言差异（尤其少见方言或重口音）增加识别难度
-
语言和词汇：多语言混合、专业术语或俚语增加识别难度，可通过配置热词优化特定领域术语的准确率
优化方法：
-
优化音频质量：使用高性能麦克风，按推荐采样率录音，尽量减少环境噪声与回声
-
适配说话人：对于口音较重或方言明显的音频，选用支持对应方言的模型
-
配置热词：为专业术语、专有名词等设置热词
该文章对您有帮助吗？