Alibaba Cloud Model Studio：非即時語音辨識（Qwen-Audio-ASR）HarmonyOS SDK

url

string

是

服務位址，固定為 wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation。呼叫時請將{WorkspaceId}替換為真實的Workspace ID。

apikey

string

是

API Key。建議使用時效性短、安全性更高的 臨時 API Key，以降低長期有效 Key 外洩的風險。

service_mode

string

是

執行模式。非即時語音辨識固定為 "1"。

device_id

string

是

用於識別終端使用者的唯一字串，可設為應用程式內使用者 ID 或用戶端產生的裝置唯一識別碼。此 ID 主要用於日誌追蹤和問題排查。

debug_path

string

否

記錄檔的儲存路徑。 此參數僅在呼叫initializeFileTrans介面時將save_log設為true時生效。此時必須設定記錄檔路徑，否則將回報錯誤。 本機最多保留兩個記錄檔。

max_log_file_size

number

否

設定記錄檔的最大位元組數。 此參數僅在呼叫initializeFileTrans介面時將save_log設為true時生效。 預設值：104857600（100 * 1024 * 1024 位元組, 即 100MiB）。

apikey

string

否

如果連線與控制參數的apikey使用的是臨時API Key，可在此處進行更新，以免逾時失效。

nls_config

object

是

語音辨識核心設定物件，包含模型選擇、辨識效果控制等關鍵參數。

nls_config.model

string

是

模型名稱。

nls_config.format

string

是

音訊格式。根據實際音訊格式填寫，支援wav、mp3、opus等。詳情請參見音訊規格。

nls_config.sample_rate

string

否

音訊取樣率，單位Hz。例如16000表示16kHz取樣率。詳情請參見音訊規格。

nls_config.vocabulary_id

string

否

預編譯熱詞清單 ID。 需預先呼叫建立熱詞清單介面產生，識別時傳入該 ID 即可使用清單中的熱詞。 適用於詞彙已知且相對穩定、需要跨請求複用同一詞表的場景。 使用方法請參見預編譯熱詞。

nls_config.instant_vocabulary

object

否

即時熱詞。

以鍵值對形式傳入，鍵為熱詞文字（string），值為熱詞權重（integer），無需預先建立熱詞清單。權重取值範圍為 [1, 5] 或 50：取 [1, 5] 時值越大模型越傾向輸出該詞；取 50 時為超級熱詞，召回率大幅提升，但超級熱詞數量最多不超過 50 個。

適用於臨時性、工作階段層級的熱詞最佳化。

與預編譯熱詞同時設定時，系統會合併兩類熱詞；合併後超過 2000 個時，隨機選擇 2000 個使用。使用方法請參見即時熱詞。

{
 "张三": 5,
 "李四": 5
}

nls_config.language_hints

array[string]

否

設定待辨識語言代碼。如果無法提前確定語種，可不設定，模型會自動辨識語種。最多支援設定 4 個值，超出時僅前 4 個生效。

指定語種代碼可提升辨識準確率。

messages

array[object]

是

訊息列表。包含當前待識別的音訊，以及可選的對話上下文（用於提升識別效果）。

role

string

是

訊息角色。取值範圍：

• user（必選）：使用者訊息。type為input_audio時表示當前待識別的音訊；type為input_text時表示前幾輪的識別結果或領域相關的詞表（可選，上下文）。

• assistant（可選，上下文）：前幾輪大型語言模型的回覆內容。

content

array[object]

是

訊息內容清單。詳細如下說明。

type

string

是

內容類型。每個請求至少需要一條input_audio類型的訊息。取值範圍：

• input_audio（必選）：當前待識別的音訊輸入（role為user），需同時傳入input_audio物件。

• input_text（可選，上下文）：前幾輪使用者語音的識別結果或領域相關的詞表（role為user），需同時傳入text欄位。

• text（可選，上下文）：前幾輪大型語言模型的回覆內容（role為assistant），需同時傳入text欄位。

input_audio

object

否

當type為input_audio時必填。

input_audio.data

string

是

待識別音訊資料。關於支援的音訊格式、檔案大小限制、時長限制等輸入要求，請參見音訊規格。支援以下兩種方式：

• 音訊檔案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}

text

string

否

當type為input_text時，填入前幾輪使用者語音的識別結果或領域相關的詞表；當type為text時，填入前幾輪大型語言模型的回覆內容。文字按字元數計算，每個字元計為 1。每輪上下文中所有訊息的 text 欄位長度之和不超過 400 個字元，超出部分從末尾截斷。

callback

INativeFileTransCallback

檔案轉錄事件和資料回呼介面的實作。

parameters

string

JSON字串，包含驗證、連線和偵錯參數。參見連線與控制參數。

level

number

控制SDK自身記錄的列印層級，取值為列舉。

save_log

boolean

是否儲存本機日誌。若為 true，須在 連線與控制參數 中透過 debug_path 指定路徑，並可透過 max_log_file_size 設定檔案大小。

params

string

語音辨識效果參數中的nls_config參數，nls_config之外的參數不支援透過此方法進行設定。

params

string

語音識別效果參數。

範例：

{
 "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_id

ArrayBuffer

任務ID緩衝區。SDK會將內部產生的隨機任務ID字串寫入該緩衝區，要求緩衝區位元組長度必須 >= 33位元組（範例中使用 new ArrayBuffer(64)）。呼叫成功後可透過轉碼獲取該任務的task_id。

task_id

string

待查詢的任務ID（由 startFileTranscriber 寫入緩衝區獲得）。

task_id

string

待取消的任務ID。

event

Constants.NuiEvent

回調事件。

resultCode

number

僅在出現 EVENT_ASR_ERROR 事件時有效。

finish

number

任務是否結束標記。

asrResult

AsrResult

語音辨識結果。

taskId

string

任務 ID。

EVENT_FILE_TRANS_CONNECTED

連線服務成功。

EVENT_FILE_TRANS_UPLOADED

上傳待識別音訊檔案成功。

EVENT_FILE_TRANS_QUERY_RESULT

查詢任務結果。

EVENT_FILE_TRANS_RESULT

辨識最終結果。

EVENT_ASR_ERROR

語音辨識過程中出現錯誤。