關於支援的音訊格式、檔案大小限制、時長限制等輸入要求,請參見音訊規格 。
快速開始
取得API Key: 取得API Key ,為安全起見,建議將API Key設定至環境變數。
下載 SDK 並執行範例程式碼:
下載最新SDK整合包 。
解壓縮 TAR 套件。在 neonui 目錄中獲取 HAR 格式 SDK,並新增至專案相依性。需要 C++ 接入時,使用 TAR 套件內的 native/libs 與 native/include 獲取動態連結庫和標頭檔。
使用 DevEco Studio 開啟專案。範例程式碼位於 DashFunAsrFlashFileTranscriberPage.ets,替換 API Key 後體驗功能。
呼叫步驟
同步模式
初始化 SDK
依業務需求設定相關參數
呼叫 startFileTranscriber 傳送非即時語音識別請求,並等待結果返回。
在onFileTransEventCallback介面中監聽EVENT_FILE_TRANS_RESULT 事件,獲取最終識別結果。
呼叫 release 釋放 SDK 資源
請求參數
連線與控制參數
透過在initializeFileTrans介面的parameters參數中傳入一個JSON字串來設定。
參數範例: 以下為 JSON 字串範例,參數未完整列出。請按實際需求在編碼時補充:
{
"url" : "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation" ,
"apikey" : "st-****" ,
"device_id" : "my_device_id" ,
"service_mode" : "1"
}
參數說明
參數 類型 是否必須 說明 urlstring是 服務位址,固定為 wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation。呼叫時請將{WorkspaceId}替換為真實的Workspace ID 。 apikeystring是 API Key。建議使用時效性短、安全性更高的 臨時 API Key ,以降低長期有效 Key 外洩的風險。 service_modestring是 執行模式。非即時語音辨識固定為 "1"。 device_idstring是 用於識別終端使用者的唯一字串,可設為應用程式內使用者 ID 或用戶端產生的裝置唯一識別碼。此 ID 主要用於日誌追蹤和問題排查。 debug_pathstring否 記錄檔的儲存路徑。 此參數僅在呼叫initializeFileTrans介面時將save_log設為true時生效。此時必須設定記錄檔路徑,否則將回報錯誤。 本機最多保留兩個記錄檔。 max_log_file_sizenumber否 設定記錄檔的最大位元組數。 此參數僅在呼叫initializeFileTrans介面時將save_log設為true時生效。 預設值:104857600(100 * 1024 * 1024 位元組, 即 100MiB)。
語音辨識效果參數
透過setParams介面設定nls_config參數,或者透過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 個使用。使用方法請參見即時熱詞 。 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: 斯洛伐克語
qwen-audio-3.1-asr-flash 還支援以下語言代碼:
tr: 土耳其語
fa: 波斯語
mr: 馬拉地語
ml: 馬拉雅拉姆語
ne: 尼泊爾語
ky: 吉爾吉斯語
az: 阿塞拜疆語
ka: 格魯吉亞語
hy: 亞美尼亞語
sl: 斯洛文尼亞語
sq: 阿爾巴尼亞語
et: 愛沙尼亞語
lv: 拉脫維亞語
lt: 立陶宛語
ca: 加泰羅尼亞語
eu: 巴斯克語
gl: 加利西亞語
or: 奧里亞語
dv: 迪維希語
as: 阿薩姆語
kmr: 北庫爾德語
tig: 提格雷語
fy: 西弗里西亞語
ba: 巴什基爾語
be: 白俄羅斯語
tt: 韃靼語
ia: 國際語
mhr: 草原馬里語
tok: 道本語
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
initializeFileTrans
初始化語音識別SDK執行個體。
與即時語音識別不同,非即時(錄音檔案)轉錄必須使用 initializeFileTrans 方法並傳入 INativeFileTransCallback 回呼,而不是 initialize。
此介面會引起阻塞,應在非 UI 執行緒呼叫。
方法簽章
public initializeFileTrans ( callback : INativeFileTransCallback ,
parameters : string ,
level : number ,
save_log : boolean = false ): number
參數說明
參數 類型 說明 callbackINativeFileTransCallback檔案轉錄事件和資料回呼介面的實作。 parametersstringJSON字串,包含驗證、連線和偵錯參數。參見連線與控制參數。 levelnumber控制SDK自身記錄的列印層級,取值為列舉。 save_logboolean是否儲存本機日誌。若為 true,須在 連線與控制參數 中透過 debug_path 指定路徑,並可透過 max_log_file_size 設定檔案大小。
setParams
此介面用於獨立設定或更新 nls_config 參數。如果所有參數都在startFileTranscriber中一次性提供,則無需呼叫此方法。
方法簽章
public setParams ( params : string ): number
參數說明
參數 類型 說明 paramsstring語音辨識效果參數中的nls_config參數,nls_config之外的參數不支援透過此方法進行設定。
startFileTranscriber
開始辨識。
方法簽章
public startFileTranscriber ( params : string , task_id : ArrayBuffer ): number
參數說明
參數 類型 說明 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_idArrayBuffer任務ID緩衝區。SDK會將內部產生的隨機任務ID字串寫入該緩衝區,要求緩衝區位元組長度必須 >= 33位元組 (範例中使用 new ArrayBuffer(64))。呼叫成功後可透過轉碼獲取該任務的task_id。
queryFileTranscriber
此介面用於主動查詢一個非同步任務的當前狀態和結果。呼叫成功後,結果將透過onFileTransEventCallback回呼中的 EVENT_FILE_TRANS_QUERY_RESULT 事件返回。
方法簽章
public queryFileTranscriber ( task_id : string ): number
參數說明
參數 類型 說明 task_idstring待查詢的任務ID(由 startFileTranscriber 寫入緩衝區獲得)。
cancelFileTranscriber
立即取消目前任務。
方法簽章
public cancelFileTranscriber ( task_id : string ): number
參數說明
參數 類型 說明 task_idstring待取消的任務ID。
release
釋放SDK所有內部資源。此方法呼叫後,SDK執行個體將變為不可用狀態,如需再次使用,必須重新呼叫initializeFileTrans進行初始化。
方法簽章
GetVersion
取得目前 SDK 版本資訊。
方法簽章
public GetVersion (): string
傳回值說明
目前 SDK 版本資訊。
INativeFileTransCallback:監聽回呼
onFileTransEventCallback:監聽事件和語音辨識結果
方法簽章
onFileTransEventCallback : ( event : Constants . NuiEvent , resultCode : number , finish : number ,
asrResult : AsrResult , taskId : string ) => void ;
參數說明
參數 類型 說明 eventConstants.NuiEvent回調事件。 resultCodenumber僅在出現 EVENT_ASR_ERROR 事件時有效。 finishnumber任務是否結束標記。 asrResultAsrResult語音辨識結果。 taskIdstring任務 ID。
onFileTransLogTrackCallback:監聽追蹤日誌
此回調用於接收 SDK 內部的詳細日誌,方便進行問題定位和偵錯。
使用此回呼需下載 20260908 或更新的 HarmonyOS SDK 套件。
onFileTransLogTrackCallback ?: ( level : Constants . LogLevel , log : string ) => void ;
事件類型
HarmonyOS SDK 中事件類型透過 Constants.NuiEvent 列舉定義,以下列出錄音檔案轉錄相關的事件:
事件 說明 EVENT_FILE_TRANS_CONNECTED連線服務成功。 EVENT_FILE_TRANS_UPLOADED上傳待識別音訊檔案成功。 EVENT_FILE_TRANS_QUERY_RESULT查詢任務結果。 EVENT_FILE_TRANS_RESULT辨識最終結果。 EVENT_ASR_ERROR語音辨識過程中出現錯誤。