錄音檔案識別-千問 - Alibaba Cloud Model Studio

核心功能

多語種識別：支援多語種語音辨識（涵蓋普通話及多種方言，如粵語、四川話等）。
複雜環境適應：具備應對複雜聲學環境的能力，支援自動語種檢測與智能非人聲過濾。
歌唱識別：即使在伴隨背景音樂（BGM）的情況下，也能實現整首歌曲的轉寫。
情感識別：支援多種情緒狀態識別（涵蓋驚訝、平靜、愉快、悲傷、厭惡、憤怒和恐懼）。

適用範圍

支援的模型：

服務主要提供兩大核心模型：

千問3-ASR-Flash-Filetrans：專為長音頻（最長12小時）的非同步識別設計，適用於會議記錄、訪談整理等情境。
千問3-ASR-Flash：專為短音頻（最長5分鐘）的同步或流式識別設計，適用於語音訊息、即時字幕等情境。

國際

在國際部署模式下，存取點與資料存放區均位於新加坡地區，模型推理計算資源在全球範圍內動態調度（不含中國內地）。

調用以下模型時，請選擇新加坡地區的API Key：

千問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-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 Key：

千問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-2025-09-08（快照版）

更多資訊請參見模型列表

模型選型

情境	推薦模型	理由	注意事項
長音頻識別	qwen3-asr-flash-filetrans	支援最長12小時錄音，具備情感識別與句/字層級時間戳記功能，適合後期索引與分析	音頻檔案大小不超過2GB，且時間長度不超過12小時
短音頻識別	qwen3-asr-flash或qwen3-asr-flash-us	短音頻識別，低延遲	音頻檔案大小不超過10MB，且時間長度不超過5分鐘
客服質檢	qwen3-asr-flash-filetrans、qwen3-asr-flash或qwen3-asr-flash-us	可分析客戶情緒	不支援敏感詞過濾；無說話人分離；根據音頻時間長度選擇合適的模型
新聞/訪談節目字幕產生	qwen3-asr-flash-filetrans	長音頻+標點預測+時間戳記，直接產生結構化字幕	需後處理產生標準字幕檔案；根據音頻時間長度選擇合適的模型
多語種視頻本地化	qwen3-asr-flash-filetrans、qwen3-asr-flash或qwen3-asr-flash-us	覆蓋多種語言+方言，適合跨語種字幕製作	根據音頻時間長度選擇合適的模型
歌唱類音頻分析	qwen3-asr-flash-filetrans、qwen3-asr-flash或qwen3-asr-flash-us	識別歌詞並分析情緒，適用於歌曲索引與推薦	根據音頻時間長度選擇合適的模型

更多說明請參見模型功能特性對比。

快速開始

API 使用前提：已擷取API Key與API Host。如果通過SDK調用，需要安裝最新版SDK。

DashScope

千問3-ASR-Flash-Filetrans

千問3-ASR-Flash-Filetrans模型專為音頻檔案的非同步轉寫設計，支援最長12小時錄音。該模型要求輸入為公網可訪問的音頻檔案URL，不支援直接上傳本地檔案。此外，它是一個非流式介面，會在任務完成後一次性返回全部識別結果。

cURL

使用 cURL 進行語音辨識時，需先提交任務擷取任務ID（task_id），再通過該ID擷取任務執行結果。

提交任務

# ======= 重要提示 =======
# 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription
# 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === 執行時請刪除該注釋 ===

curl -X POST 'https://dashscope-intl.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.aliyuncs.com/api/v1/tasks/{task_id}，注意，將{task_id}替換為待查詢任務ID
# 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === 執行時請刪除該注釋 ===

curl -X GET 'https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "X-DashScope-Async: enable" \
-H "Content-Type: application/json"

完整樣本

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.aliyuncs.com/api/v1/services/audio/asr/transcription
    private static final String API_URL_SUBMIT = "https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/transcription";
    // 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/api/v1/tasks/
    private static final String API_URL_QUERY = "https://dashscope-intl.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

# 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription
API_URL_SUBMIT = "https://dashscope-intl.aliyuncs.com/api/v1/services/audio/asr/transcription"
# 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/api/v1/tasks/
API_URL_QUERY_BASE = "https://dashscope-intl.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) {
        // 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/api/v1
        Constants.baseHttpApiUrl = "https://dashscope-intl.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);
            // 查詢任務狀態
            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")

    # 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/api/v1
    dashscope.base_http_api_url = 'https://dashscope-intl.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.aliyuncs.com/api/v1，若使用美國地區的模型，需將url替換為：https://dashscope-us.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

messages = [
    {"role": "system", "content": [{"text": ""}]},  # 配置定製化識別的 Context
    {"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();

        MultiModalMessage sysMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())
                // 此處用於配置定製化識別的Context
                .content(Arrays.asList(Collections.singletonMap("text", "")))
                .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(sysMessage)
                .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.aliyuncs.com/api/v1，若使用美國地區的模型，需將url替換為：https://dashscope-us.aliyuncs.com/api/v1
            Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
            simpleMultiModalConversationCall();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

cURL

通過System Message的text參數，可以配置Context進行定製化識別。

# ======= 重要提示 =======
# 以下為新加坡地區url若使用美國地區的模型，需將url替換為：https://dashscope-us.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
# 新加坡/美國地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若使用美國地區的模型，需要加us尾碼
# === 執行時請刪除該注釋 ===

curl -X POST "https://dashscope-intl.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

import base64, pathlib

# input.mp3為用於聲音複刻的本地音頻檔案，請替換為自己的音頻檔案路徑，確保其符合音頻要求
file_path = pathlib.Path("input.mp3")
base64_str = base64.b64encode(file_path.read_bytes()).decode()
data_uri = f"data:audio/mpeg;base64,{base64_str}"

Java

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

public class Main {
    /**
     * filePath為用於聲音複刻的本地音頻檔案，請替換為自己的音頻檔案路徑，確保其符合音頻要求
     */
    public static String toDataUrl(String filePath) throws Exception {
        byte[] bytes = Files.readAllBytes(Paths.get(filePath));
        String encoded = Base64.getEncoder().encodeToString(bytes);
        return "data:audio/mpeg;base64," + encoded;
    }

    // 使用樣本
    public static void main(String[] args) throws Exception {
        System.out.println(toDataUrl("input.mp3"));
    }
}

Python SDK

樣本中用到的音頻檔案為：welcome.mp3。

import base64
import dashscope
import os
import pathlib

# 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/api/v1，若使用美國地區的模型，需將url替換為：https://dashscope-us.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.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": "system", "content": [{"text": ""}]},  # 配置定製化識別的 Context
    {"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();

        MultiModalMessage sysMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())
                // 此處用於配置定製化識別的Context
                .content(Arrays.asList(Collections.singletonMap("text", "")))
                .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(sysMessage)
                .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.aliyuncs.com/api/v1，若使用美國地區的模型，需將url替換為：https://dashscope-us.aliyuncs.com/api/v1
            Constants.baseHttpApiUrl = "https://dashscope-intl.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
Linux或macOS系統	Java SDK	file://{檔案的絕對路徑}	file:///home/images/test.png
Windows系統	Python SDK	file://{檔案的絕對路徑}	file://D:/images/test.png
Windows系統	Java SDK	file:///{檔案的絕對路徑}	file:///D:images/test.png

重要

使用本地檔案時，介面調用上限為 100 QPS，且不支援擴容，請勿用於生產環境、高並發及壓測情境；如需更高並發，建議將檔案上傳至 OSS 並通過錄音檔案 URL 方式調用。

Python SDK

樣本中用到的音頻檔案為：welcome.mp3。

import os
import dashscope

# 以下為新加坡地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/api/v1，若使用美國地區的模型，需將url替換為：https://dashscope-us.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

# 請用您的本地音訊絕對路徑替換 ABSOLUTE_PATH/welcome.mp3
audio_file_path = "file://ABSOLUTE_PATH/welcome.mp3"

messages = [
    {"role": "system", "content": [{"text": ""}]},  # 配置定製化識別的 Context
    {"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();

        MultiModalMessage sysMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())
                // 此處用於配置定製化識別的Context
                .content(Arrays.asList(Collections.singletonMap("text", "")))
                .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(sysMessage)
                .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.aliyuncs.com/api/v1，若使用美國地區的模型，需將url替換為：https://dashscope-us.aliyuncs.com/api/v1
            Constants.baseHttpApiUrl = "https://dashscope-intl.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.aliyuncs.com/api/v1，若使用美國地區的模型，需將url替換為：https://dashscope-us.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

messages = [
    {"role": "system", "content": [{"text": ""}]},  # 配置定製化識別的 Context
    {"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:
        pass

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 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();

        MultiModalMessage sysMessage = MultiModalMessage.builder().role(Role.SYSTEM.getValue())
                // 此處用於配置定製化識別的Context
                .content(Arrays.asList(Collections.singletonMap("text", "")))
                .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(sysMessage)
                .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.aliyuncs.com/api/v1，若使用美國地區的模型，需將url替換為：https://dashscope-us.aliyuncs.com/api/v1
            Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
            simpleMultiModalConversationCall();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

cURL

通過System Message的text參數，可以配置Context進行定製化識別。

# ======= 重要提示 =======
# 以下為新加坡地區url若使用美國地區的模型，需將url替換為：https://dashscope-us.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
# 新加坡地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若使用美國地區的模型，需要加us尾碼
# === 執行時請刪除該注釋 ===

curl -X POST "https://dashscope-intl.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
        }
    }
}'

OpenAI相容

重要

美國地區不支援OpenAI相容模式。

僅千問3-ASR-Flash系列模型支援OpenAI相容方式調用。OpenAI相容方式僅允許輸入公網可訪問的音頻檔案URL，不支援輸入本地音頻檔案絕對路徑。

OpenAI Python SDK 版本應不低於1.52.0， Node.js SDK 版本應不低於 4.68.0。

asr_options非OpenAI標準參數，若使用OpenAI SDK，請通過extra_body傳入。

輸入內容：音頻檔案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"),
        # 以下為新加坡/美國地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
        base_url="https://dashscope-intl.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,
  // 以下為新加坡/美國地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
  baseURL: "https://dashscope-intl.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

通過System Message的text參數，可以配置Context進行定製化識別。

# ======= 重要提示 =======
# 以下為新加坡/美國地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
# 新加坡/美國地區和北京地區的API Key不同。擷取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === 執行時請刪除該注釋 ===

curl -X POST 'https://dashscope-intl.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

import base64, pathlib

# input.mp3為用於聲音複刻的本地音頻檔案，請替換為自己的音頻檔案路徑，確保其符合音頻要求
file_path = pathlib.Path("input.mp3")
base64_str = base64.b64encode(file_path.read_bytes()).decode()
data_uri = f"data:audio/mpeg;base64,{base64_str}"

Java

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

public class Main {
    /**
     * filePath為用於聲音複刻的本地音頻檔案，請替換為自己的音頻檔案路徑，確保其符合音頻要求
     */
    public static String toDataUrl(String filePath) throws Exception {
        byte[] bytes = Files.readAllBytes(Paths.get(filePath));
        String encoded = Base64.getEncoder().encodeToString(bytes);
        return "data:audio/mpeg;base64," + encoded;
    }

    // 使用樣本
    public static void main(String[] args) throws Exception {
        System.out.println(toDataUrl("input.mp3"));
    }
}

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"),
        # 以下為新加坡/美國地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
        base_url="https://dashscope-intl.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,
  // 以下為新加坡/美國地區url，若使用北京地區的模型，需將url替換為：https://dashscope.aliyuncs.com/compatible-mode/v1
  baseURL: "https://dashscope-intl.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();

API參考

錄音檔案識別-千問API參考

模型功能特性對比

下表中qwen3-asr-flash和qwen3-asr-flash-2025-09-08模型的功能特性同樣適用於美國（維吉尼亞）地區對應的qwen3-asr-flash-us和qwen3-asr-flash-2025-09-08-us模型。

功能/特性	qwen3-asr-flash-filetrans、qwen3-asr-flash-filetrans-2025-11-17	qwen3-asr-flash、qwen3-asr-flash-2025-09-08
支援語言	中文（普通話、四川話、閩南語、吳語、粵語）、英語、日語、德語、韓語、俄語、法語、葡萄牙語、阿拉伯語、意大利語、西班牙語、印地語、印尼語、泰語、土耳其語、烏克蘭語、越南語、捷克語、丹麥語、菲律賓語、芬蘭語、冰島語、馬來語、挪威語、波蘭語、瑞典語
支援的音頻格式	aac、amr、avi、flac、flv、m4a、mkv、mov、mp3、mp4、mpeg、ogg、opus、wav、webm、wma、wmv	aac、amr、avi、aiff、flac、flv、mkv、mp3、mpeg、ogg、opus、wav、webm、wma、wmv
採樣率	因音頻格式而異： pcm格式音頻：16kHz 其他格式音頻：任意（服務端會先將音頻重採樣為 16 kHz，再進行識別）
聲道	任意不同模型在處理多頻道音訊時方式存在差異：千問3-ASR-Flash-Filetrans：需通過`channel_id`參數指定音軌索引千問3-ASR-Flash：無需額外處理，模型會對多頻道音訊做均值合并後再處理
輸入形式	公網可訪問的待識別檔案URL	Base64編碼的檔案、本地檔案絕對路徑、公網可訪問的待識別檔案URL
音頻大小/時間長度	音頻檔案大小不超過2GB，且時間長度不超過12小時	音頻檔案大小不超過10MB，且時間長度不超過5分鐘
情感識別	支援固定開啟，可通過響應參數`emotion`查看結果
時間戳記	支援固定開啟，可通過請求參數`enable_words`控制時間戳記層級字層級時間戳記僅支援以下語種：中文、英語、日語、韓語、德語、法語、西班牙語、意大利語、葡萄牙語、俄語，其他語種可能無法保證準確性	不支援
標點符號預測	支援固定開啟
ITN	支援預設關閉，可開啟，僅適用於中、英文
歌唱識別	支援固定開啟
雜訊拒識	支援固定開啟
敏感詞過濾	不支援
說話人分離	不支援
語氣詞過濾	不支援
VAD	支援固定開啟	不支援
限流（RPM）	100
接入方式	DashScope：Java/Python SDK、RESTful API	DashScope：Java/Python SDK、RESTful API OpenAI：Python/Node.js SDK、RESTful API
價格	國際：$0.000035/秒美國：$0.000032/秒中國內地：$0.000032/秒

常見問題

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.mp3

Q：如何處理音頻以滿足模型要求？

可以使用開源工具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