Skip to main content

Qwen-Audio-ASR-Filetrans非即時語音識別Android SDK

本文檔提供了Qwen-Audio-ASR-Filetrans非即時語音識別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 打開工程。示例程式碼位於DashFunAsrFileTranscriberActivity.java,替換 API Key 後體驗功能。

呼叫步驟

  • 同步模式
  • 非同步模式
  1. 初始化 SDK
  2. 按業務需求設定相關參數
  3. 當 async_request 設為 false 時,呼叫 startFileTranscriber 發送非即時語音識別請求,並等待結果返回。
  4. 在onFileTransEventCallback介面中監聽EVENT_FILE_TRANS_RESULT 事件,取得最終識別結果
  5. 呼叫 release 釋放 SDK 資源

請求參數

連接與控制參數

通過在initialize介面的parameters參數中傳入一個JSON字串來設定。 參數示例 以下為 JSON 字串示例,參數未完整列出。請按實際需求在編碼時補充:
{
    "url": "wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
參數說明
參數類型是否必須說明
urlString是服務地址:
  • wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription
  • 華北2(北京):wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
  • 新加坡:wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
呼叫時,請將 {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-****",
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}
參數說明
參數類型是否必須說明
file_urlsarray[string]是音視訊檔案轉寫的URL列表,支援HTTP / HTTPS協議,單次請求僅支援1個URL。關於支援的音訊格式、檔案大小限制、時長限制等輸入要求,請參見音訊規格。若錄音檔案存儲在阿里雲OSS,使用RESTful API方式支援使用以oss://為前綴的臨時 URL,使用SDK方式不支援使用以 oss://為前綴的臨時 URL。
  • 臨時 URL 有效期48小時,過期後無法使用,請勿用於生產環境。
  • 檔案上傳憑證介面限流為 100 QPS 且不支援擴容,請勿用於生產環境、高並行及壓測場景。
  • 生產環境建議使用阿里雲OSS 等穩定存儲,確保檔案長期可用並規避限流問題。
  • 錄音檔案URL設定成OSS臨時公網訪問不通該如何處理?請求頭中將X-DashScope-OssResourceResolve設為enable(不推薦該方式)。 SDK不支援對請求頭進行設定。
async_requestboolean否語音識別是否為非同步請求。預設值:false。取值範圍:
  • true:非同步請求
  • false:同步請求
apikeystring否如果連接與控制參數的apikey使用的是臨時API Key,可在此處進行更新,以免超時失效。
nls_configobject是語音識別核心設定對象,包含模型選擇、識別效果控制等關鍵參數。
nls_config.modelstring是模型名稱。
nls_config.special_word_filterobject否指定在語音識別過程中需要處理的敏感詞,並支援對不同敏感詞設定不同的處理方式。詳情請參見敏感詞過濾。
nls_config.channel_idarray[integer]否指定在多音軌音訊檔案中需要識別的音軌索引,索引從 0 開始。例如,[0] 表示識別第一個音軌,[0, 1] 表示同時識別第一和第二個音軌。如果省略此參數,則預設處理第一個音軌。
指定的每一個音軌都將獨立計費。例如,為單個檔案請求 [0, 1] 會產生兩筆獨立的費用。
預設值:[0]。
nls_config.diarization_enabledboolean否是否啓用說話人分離,預設關閉。僅適用於單聲道音訊,多聲道音訊不支援說話人分離。啓用該功能後,識別結果中將顯示speaker_id字段,用於區分不同說話人。
如果啓用說話人分離功能,建議音訊時長不超過2小時,否則可能導致識別失敗或超時。
預設值:false。有關speaker_id的示例,請參見識別結果說明。
nls_config.speaker_countinteger否
僅在開啓說話人分離功能(diarization_enabled設定為true)時生效。
說話人數量參考值。取值範圍為2至100的整數(包含2和100)。預設自動判斷說話人數量,如果設定此項,只能輔助算法盡量輸出指定人數,無法保證一定會輸出此人數。無預設值。
nls_config.vocabulary_idstring否預編譯熱詞列表 ID。需預先呼叫建立熱詞列表介面生成,識別時傳入該 ID 即可使用列表中的熱詞。適用於詞彙已知且相對穩定、需要跨請求復用同一詞表的場景。使用方法請參見預編譯熱詞。
nls_config.input_contextarray否消息列表,包含用於提升識別效果的可選對話上下文。
上下文功能用於提升專有詞彙的識別準確率,使用方法請參見上下文增強。上下文消息(input_text 和 text 類型)各最多 5 條,超出時保留最近的 5 條。每輪上下文文本總長度(user 和 assistant 的 text 字段長度之和)不超過 400 個字符,每個字符計為 1,超出部分從末尾截斷。
攜帶上下文時,messages 中的消息必須按對話輪次排列,每輪中 user(input_text 類型)必須在對應的 assistant(text 類型)之前;包含 input_audio 的 user 消息必須放在 messages 數組的最後。
[
  {
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "你好啊,我是通义千问,有什么可以帮助你的?"
      }
    ]
  }
]
nls_config.instant_vocabularyobject否即時熱詞,以鍵值對形式傳入:鍵為熱詞文本(string),值為熱詞權重(integer),無需預先建立熱詞列表。適用於臨時性、會話級別的熱詞優化。權重取值範圍為 1 至 5 或 50。取 1 至 5 時,值越大,模型越傾向於輸出該詞;取 50 時為超級熱詞,召回率大幅提升,但超級熱詞最多不超過 50 個。與預編譯熱詞同時設定時,系統會合併兩類熱詞;合併後超過 2000 個時,隨機選擇 2000 個使用。使用方法請參見即時熱詞。
{
  "张三": 5,
  "李四": 5
}
nls_config.language_hintsarray[string]否設定待識別語言程式碼。如果無法提前確定語種,可不設定,模型會自動識別語種。最多支援設定 4 個值,超出時僅前 4 個生效。
  • 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:斯洛伐克語
  • fun-asr-2025-08-25:
    • zh: 中文
    • en: 英文

關鍵介面

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參數,nls_config之外的參數不支援通過該方法進行設定。示例:
{
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}

startFileTranscriber

開始識別。 方法簽名
public synchronized int startFileTranscriber(String params, byte[] task_id)
參數說明
參數類型說明
paramsString語音識別效果參數。示例:
{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"qwen-audio-3.0-asr-flash-filetrans",
        "diarization_enabled": false
    }
}
task_idbyte[]任務ID,SDK內部生成隨機字串,在此介面呼叫成功後可獲得task_id。

queryFileTranscriber

此介面用於主動查詢一個非同步任務的當前狀態和結果。呼叫成功後,結果將通過onFileTransEventCallback回呼中的 EVENT_FILE_TRANS_QUERY_RESULT 事件返回。
此處傳入的 task_id 從 EVENT_FILE_TRANS_UPLOADED 事件中取得。
方法簽名
public synchronized int queryFileTranscriber(String task_id)
參數說明
參數類型說明
task_idString待查詢的任務 ID,從 EVENT_FILE_TRANS_UPLOADED 事件中取得。

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)

NuiEvent:事件類型

事件說明
EVENT_FILE_TRANS_CONNECTED連接服務成功。
EVENT_FILE_TRANS_UPLOADED上傳待識別音訊檔案成功,此時可獲得當前任務的 task_id。
EVENT_FILE_TRANS_QUERY_RESULT查詢任務結果。
EVENT_FILE_TRANS_RESULT識別最終結果。
EVENT_ASR_ERROR語音識別過程中出現錯誤。