Skip to main content

非即時語音識別（Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash）Android SDK

Qwen-Audio-3.x-ASR-Flash/Fun-ASR-Flash非即時語音識別Android SDK可將語音轉換為文字。

使用者指南：非即時語音辨識。關於支援的音訊格式、檔案大小限制、時長限制等輸入要求，請參見音訊規格。

快速開始

  1. 取得API Key：取得API Key，為安全起見，建議將API Key設定至環境變數。
  2. 下載 SDK 並執行範例程式碼：
    • 下載最新SDK整合包。
    • 解壓縮 ZIP 套件。在 app/libs 目錄中獲取 AAR 格式 SDK，並新增至專案相依性。 需要 Android CPP 接入時，使用 ZIP 套件內的 android_libs 與 android_include 獲取動態連結庫和標頭檔。
    • 使用 Android Studio 開啟專案。範例程式碼位於 DashFunAsrFlashFileTranscriberActivity.java，替換 API Key 後體驗功能。

呼叫步驟

同步模式

  1. 初始化 SDK
  2. 依業務需求設定相關參數
  3. 呼叫 startFileTranscriber 傳送非即時語音辨識請求，並等待結果返回。
  4. 在onFileTransEventCallback介面中監聽EVENT_FILE_TRANS_RESULT 事件，獲取最終識別結果。
  5. 呼叫 release 釋放 SDK 資源

請求參數

連線與控制參數

透過在initialize介面的parameters參數中傳入一個JSON字串來設定。 參數範例：以下為 JSON 字串範例，參數未完整列出。請按實際需求在編碼時補充： 
{
    "url": "wss://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
參數說明
參數類型是否必須說明
urlString是服務位址：
  • wss://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
  • 華北2（北京）：wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
  • 新加坡：wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

呼叫時，請將 {WorkspaceId} 替換為真實的 Workspace ID。
apikeyString是API Key。
service_modeString是執行模式。非即時語音辨識固定為 "1"。
device_idString是用於識別終端使用者的唯一字串，可設為應用程式內使用者 ID 或用戶端產生的裝置唯一識別碼。此 ID 主要用於日誌追蹤和問題排查。
debug_pathString否日誌檔案的儲存路徑。此參數僅在呼叫 initialize 介面時將 save_log 設為 true 時生效。此時必須設定日誌檔案路徑，否則將報錯。本機最多保留兩個日誌檔案。
max_log_file_sizeint否設定記錄檔的最大位元組數。 此參數僅在呼叫initialize介面時將save_log設為true時生效。 預設值：104857600（100 * 1024 * 1024 位元組, 即 100MiB）。
log_track_levelint否控制透過記錄回呼（onFileTransLogTrackCallback）對外傳送的記錄內容的篩選層級。 預設值：2。 取值範圍： - 0：LOG_LEVEL_VERBOSE - 1：LOG_LEVEL_DEBUG - 2：LOG_LEVEL_INFO - 3：LOG_LEVEL_WARNING - 4：LOG_LEVEL_ERROR - 5：LOG_LEVEL_NONE（表示關閉此功能） 注意：log_track_level與level（透過initialize介面設定）共同決定最終回呼的記錄。一筆記錄的層級數值必須同時大於或等於log_track_level和level的值，才會被回呼。例如，log_track_level設為2 (INFO)，level設為3 (WARNING)，則只有WARNING及以上層級（數值>=3）的記錄才會被回呼。

語音辨識效果參數

透過startFileTranscriber介面設定所有語音辨識效果參數。 參數範例：以下為 JSON 字串範例，參數未完整列出。請按實際需求在編碼時補充： 
{
  "apikey": "st-****",
  "messages": [
    {
      "content": [
        {
          "input_audio": {
            "data": "{YOUR_AUDIO_URL}"
          },
          "type": "input_audio"
        }
      ],
      "role": "user"
    }
  ],
  "nls_config": {
    "format": "mp3",
    "model": "qwen-audio-3.0-asr-flash"
  }
}
參數說明
參數類型是否必須說明
apikeystring否如果連線與控制參數的apikey使用的是臨時API Key，可在此處進行更新，以免逾時失效。
nls_configobject是語音辨識核心設定物件，包含模型選擇、辨識效果控制等關鍵參數。
nls_config.modelstring是指定範例呼叫的模型。模型資訊請參見支援的模型與地域。
nls_config.formatstring是音訊格式。根據實際音訊格式填寫，支援wav、mp3、opus等。詳情請參見音訊規格。
nls_config.sample_ratestring否音訊取樣率，單位Hz。例如16000表示16kHz取樣率。詳情請參見音訊規格。
nls_config.vocabulary_idstring否預編譯熱詞清單 ID。 需預先呼叫建立熱詞清單介面產生，識別時傳入該 ID 即可使用清單中的熱詞。 適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的場景。 使用方法請參見預編譯熱詞。
nls_config.instant_vocabularyobject否即時熱詞。
以鍵值對形式傳入，鍵為熱詞文字（string），值為熱詞權重（integer），無需預先建立熱詞清單。權重取值範圍為 [1, 5] 或 50：取 [1, 5] 時值越大模型越傾向輸出該詞；取 50 時為超級熱詞，召回率大幅提升，但超級熱詞數量最多不超過 50 個。
適用於臨時性、工作階段層級的熱詞最佳化。
與預編譯熱詞同時設定時，系統會合併兩類熱詞；合併後超過 2000 個時，隨機選擇 2000 個使用。使用方法請參見即時熱詞。
即時熱詞的適用模型及限制請參見即時熱詞。

{
  "张三": 5,
  "李四": 5
}
nls_config.language_hintsarray[string]否設定待辨識語言代碼。如果無法提前確定語種，可不設定，模型會自動辨識語種。
對於 Qwen-Audio-3.x-ASR-Flash 系列模型，最多支援設定 4 個值，即便設定超出 4 個，也僅前 4 個生效；對於 Fun-ASR-Flash 系列模型，僅支援設定 1 個值，即便設定多個，也僅第一個生效。
  • Qwen-Audio-3.x-ASR-Flash、fun-asr-flash-2026-06-15：
  • zh: 中文
  • en: 英文
  • ja: 日語
  • ko：韓語
  • vi：越南語
  • th：泰語
  • id：印尼語
  • ms：馬來語
  • tl：菲律賓語
  • hi：印地語
  • ar：阿拉伯語
  • fr：法語
  • de：德語
  • es：西班牙語
  • pt：葡萄牙語
  • ru：俄語
  • it：義大利語
  • nl：荷蘭語
  • sv：瑞典語
  • da：丹麥語
  • fi：芬蘭語
  • no：挪威語
  • el：希臘語
  • pl：波蘭語
  • cs：捷克語
  • hu：匈牙利語
  • ro：羅馬尼亞語
  • bg：保加利亞語
  • hr：克羅埃西亞語
  • sk：斯洛伐克語
messagesarray[object]是訊息列表。包含當前待識別的音訊，以及可選的對話上下文（用於提升識別效果）。
詳見如下說明。
messages參數說明：
上下文功能用於提升專有詞彙的識別準確率，使用方法詳見上下文增強。約束：上下文訊息（input_text 和 text 類型）各最多 5 條，超出時保留最近的 5 條。每輪上下文文字總長度（user 和 assistant 的 text 欄位長度之和）不超過 400 個字元（按字元數計算，每個字元計為 1），超出部分從末尾截斷。
攜帶上下文時，messages 中的訊息順序有要求：上下文訊息必須按對話輪次排列，每輪中 user（input_text 類型）必須在對應的 assistant（text 類型）之前；包含 input_audio 的 user 訊息必須放在 messages 陣列的最後。
參數類型是否必須說明
rolestring是訊息角色。取值範圍：
  • user（必選）：使用者訊息。type為input_audio時表示當前待識別的音訊；type為input_text時表示前幾輪的識別結果或領域相關的詞表（可選，上下文）。
  • assistant（可選，上下文）：前幾輪大型語言模型的回覆內容。
contentarray[object]是訊息內容清單。詳細如下說明。
content參數說明：
參數類型是否必須說明
typestring是內容類型。每個請求至少需要一條input_audio類型的訊息。取值範圍：
  • input_audio（必選）：當前待識別的音訊輸入（role為user），需同時傳入input_audio物件。
  • input_text（可選，上下文）：前幾輪使用者語音的識別結果或領域相關的詞表（role為user），需同時傳入text欄位。
  • text（可選，上下文）：前幾輪大型語言模型的回覆內容（role為assistant），需同時傳入text欄位。
input_audioobject否當type為input_audio時必填。
input_audio.datastring是待識別音訊資料。關於支援的音訊格式、檔案大小限制、時長限制等輸入要求，請參見音訊規格。支援以下兩種方式：
  • 音訊檔案URL：直接傳入可公開存取的音訊檔案位址。
  • Base64 Data URI：採用Data URI格式傳入Base64編碼的音訊資料，值由data:{MIME_TYPE};base64,前綴與Base64編碼的音訊資料拼接而成。支援的MIME類型包括audio/wav、audio/mp3等。

範例（URL方式）：https://example.com/audio/sample.wav
範例（Base64方式）：data:audio/wav;base64,{BASE64_ENCODED_DATA}
textstring否當type為input_text時，填入前幾輪使用者語音的識別結果或領域相關的詞表；當type為text時，填入前幾輪大型語言模型的回覆內容。文字按字元數計算，每個字元計為 1。每輪上下文中所有訊息的 text 欄位長度之和不超過 400 個字元，超出部分從末尾截斷。

關鍵介面

NativeNui

initialize

初始化語音辨識SDK執行個體。SDK為單例模式，在呼叫release前禁止重複初始化。 此介面會引起阻塞，應在非 UI 執行緒呼叫。 方法簽章 
public synchronized int initialize(final INativeFileTransCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)
參數說明
參數類型說明
callbackINativeFileTransCallback事件和資料回調介面的實作。
parametersStringJSON字串，包含驗證、連線和偵錯參數。參見連線與控制參數。
levelConstants.LogLevel控制 SDK 自身日誌的列印層級。
save_logboolean是否儲存本機日誌。若為 true，須在 連線與控制參數 中透過 debug_path 指定路徑，並可透過 max_log_file_size 設定檔案大小。

setParams

此介面用於獨立設定或更新 nls_config 參數。如果所有參數都在startFileTranscriber中一次性提供，則無需呼叫此方法。 方法簽章 
public synchronized int setParams(String params);
參數說明
參數類型說明
paramsString語音識別效果參數中的nls_config和messages參數。
範例： 
{
  "messages": [
    {
      "content": [
        {
          "input_audio": {
            "data": "{YOUR_AUDIO_URL}"
          },
          "type": "input_audio"
        }
      ],
      "role": "user"
    }
  ],
  "nls_config": {
    "format": "mp3",
    "model": "qwen-audio-3.0-asr-flash"
  }
}

startFileTranscriber

開始辨識。 方法簽章 
public synchronized int startFileTranscriber(String params, byte[ ] task_id)
參數說明
參數類型說明
paramsString語音辨識效果參數。 範例： 
{
  "apikey": "st-****",
  "messages": [
    {
      "content": [
        {
          "input_audio": {
            "data": "{YOUR_AUDIO_URL}"
          },
          "type": "input_audio"
        }
      ],
      "role": "user"
    }
  ],
  "nls_config": {
    "format": "mp3",
    "model": "qwen-audio-3.0-asr-flash"
  }
}
task_idbyte[ ]可不關注，可填null

queryFileTranscriber

此非即時語音辨識功能僅支援同步請求，無需關注此介面。

cancelFileTranscriber

立即取消目前任務。 方法簽章 
public synchronized int cancelFileTranscriber(String task_id)
參數說明
參數類型說明
task_idString待取消的任務ID。透過EVENT_FILE_TRANS_UPLOADED取得。

release

釋放SDK所有內部資源。此方法呼叫後，SDK執行個體將變為不可用狀態，如需再次使用，必須重新呼叫initialize進行初始化。 方法簽章 
public synchronized int release();

GetVersion

取得目前 SDK 版本資訊。 方法簽章 
public synchronized String GetVersion();
傳回值說明 目前 SDK 版本資訊。

INativeFileTransCallback：監聽回呼

onFileTransEventCallback：監聽事件和語音辨識結果

方法簽章 
void onFileTransEventCallback(NuiEvent event, final int resultCode, final int arg2, AsrResult asrResult, String taskId);
參數說明
參數類型說明
eventNuiEvent回調事件。
resultCodeint僅在出現 EVENT_ASR_ERROR 事件時有效。
asrResultAsrResult語音辨識結果。
taskIdString任務 ID。
arg2int保留參數。

onFileTransLogTrackCallback：監聽追蹤日誌

此回調用於接收 SDK 內部的詳細日誌，方便進行問題定位和偵錯。 
default void onFileTransLogTrackCallback(Constants.LogLevel level, String log)

事件類型

事件說明
EVENT_FILE_TRANS_CONNECTED連線服務成功。
EVENT_FILE_TRANS_UPLOADED上傳待辨識音訊檔案成功，此時可取得目前任務的task_id。
EVENT_FILE_TRANS_RESULT辨識最終結果。
EVENT_ASR_ERROR語音辨識過程中出現錯誤。