前提條件
在控制台獲取 API Key,並配置為環境變量 DASHSCOPE_API_KEY。
安裝 SDK
需要 Node.js 18 或以上版本。下載 SDK 0.1.0 安裝包後,在項目目錄運行:
快速開始
以下呼叫範例可共用。依下表替換範例中的模型 ID。
| 模型 | 範例中的模型 ID |
|---|---|
| Qwen-Audio-ASR-Streaming | qwen-audio-3.1-asr-flash-streaming |
| Qwen-Audio-ASR-Message | qwen-audio-3.1-asr-flash-message |
input.mp3,並轉換為 16 kHz、16-bit、單聲道 PCM:
example.mjs,運行 node example.mjs。
請求參數
Qwen-Audio-ASR-Streaming
RecognitionClient 的構造參數如下。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
apiKey | string | 否 | API Key。默認讀取 DASHSCOPE_API_KEY。 |
workspaceId | string | 否 | 業務空間 ID。默認讀取 DASHSCOPE_WORKSPACE_ID。 |
baseUrl | string | 否 | 服務域名,設置為 dashscope-intl.aliyuncs.com(新加坡)。 |
model | string | 否 | 模型 ID,默認 qwen-audio-3.1-asr-flash-streaming。 |
format | 'pcm' | 'wav' | 'mp3' | 'opus' | 'speex' | 'aac' | 'amr' | 否 | 音頻格式,默認 pcm;WAV 使用 PCM 編碼,Opus/Speex 使用 Ogg 封裝,AMR 使用 AMR-NB。 |
sampleRate | number | 否 | 實際音頻採樣率(Hz),默認 16000。 |
vocabularyId | string | 否 | 預編譯熱詞列表 ID。 |
languageHints | string[] | 否 | 識別語言提示,最多使用前 4 個值;未設置時自動識別。 |
multiThresholdModeEnabled | boolean | 否 | 多閾值模式,避免 VAD 斷句過長,默認 false。 |
maxSentenceSilence | number | 否 | VAD 斷句靜音閾值(ms),範圍 [200,6000],默認 800。 |
heartbeat | boolean | 否 | 靜音保活開關,默認 false;開啓後需持續發送靜音音頻。 |
context | AsrContextMessage[] | 否 | 識別上下文。消息格式為 { role, content: [{ type: "input_text", text }] },role 為 user 或 assistant;每種角色最多 5 條,文本共少於 400 字符,按對話輪次排列。 |
parameters | Partial<RecognitionParameters> | 否 | 其他識別參數,如 vad_model、keep_dialect 和 vocabulary。 |
connectTimeoutMs | number | 否 | 建連超時(ms),默認 10000。 |
taskTimeoutMs | number | 否 | 任務啓動或結束的等待超時(ms),默認 60000;0 表示不限制。 |
parameters.vad_model | 'near_meeting_16k' | 'far_field_meeting_16k' | 否 | 近場或遠場 VAD,默認 far_field_meeting_16k。 |
parameters.keep_dialect | boolean | 否 | 保留方言表達,默認 false。 |
parameters.vocabulary | Record<string, number> | 否 | 即時熱詞:鍵為詞,值為權重 [1,5] 或 50。 |
parameters.speech_noise_threshold | number | 否 | VAD 靈敏度閾值,範圍 [-1,1]。 |
Qwen-Audio-ASR-Message
RecognitionClient 的構造參數如下。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
apiKey | string | 否 | API Key。默認讀取 DASHSCOPE_API_KEY。 |
workspaceId | string | 否 | 業務空間 ID。默認讀取 DASHSCOPE_WORKSPACE_ID。 |
baseUrl | string | 否 | 服務域名,設置為 dashscope-intl.aliyuncs.com(新加坡)。 |
model | string | 是 | 模型 ID,設置為 qwen-audio-3.1-asr-flash-message。 |
format | 'pcm' | 'wav' | 'mp3' | 'opus' | 'speex' | 'aac' | 'amr' | 否 | 音頻格式,默認 pcm;WAV 使用 PCM 編碼,Opus/Speex 使用 Ogg 封裝,AMR 使用 AMR-NB。 |
sampleRate | number | 否 | 音頻採樣率,使用 16000 Hz。 |
vocabularyId | string | 否 | 預編譯熱詞列表 ID。 |
languageHints | string[] | 否 | 識別語言提示,最多使用前 4 個值;未設置時自動識別。 |
disfluencyRemovalEnabled | boolean | 否 | 過濾語氣詞並潤色結果,默認 false。 |
maxSentenceSilence | number | 否 | VAD 斷句靜音閾值(ms),範圍 [200,6000],默認 800。 |
heartbeat | boolean | 否 | 靜音保活開關,默認 false;開啓後需持續發送靜音音頻。 |
context | AsrContextMessage[] | 否 | 識別上下文。消息格式為 { role, content: [{ type: "input_text", text }] },role 為 user 或 assistant;每種角色最多 5 條,文本共少於 400 字符,按對話輪次排列。 |
parameters | Partial<RecognitionParameters> | 否 | 其他識別參數,如 vad_model、keep_dialect 和 vocabulary。 |
connectTimeoutMs | number | 否 | 建連超時(ms),默認 10000。 |
taskTimeoutMs | number | 否 | 任務啓動或結束的等待超時(ms),默認 60000;0 表示不限制。 |
parameters.vad_model | 'near_meeting_16k' | 'far_field_meeting_16k' | 否 | 近場或遠場 VAD,默認 far_field_meeting_16k。 |
parameters.keep_dialect | boolean | 否 | 保留方言表達,默認 false。 |
parameters.vocabulary | Record<string, number> | 否 | 即時熱詞:鍵為詞,值為權重 [1,5] 或 50。 |
parameters.speech_noise_threshold | number | 否 | VAD 靈敏度閾值,範圍 [-1,1]。 |
parameters.intermediate_result_enabled | boolean | 否 | 返回識別中間結果,默認 false。 |
介面參考
Qwen-Audio-ASR-Streaming
主要方法
| 方法 | 返回值 | 說明 |
|---|---|---|
start() | Promise<void> | 啓動識別任務,完成後可發送音頻。 |
sendAudio(audio: Buffer | Uint8Array) | void | 按配置的格式和採樣率發送音頻幀。 |
finish() | Promise<void> | 結束音頻輸入並等待任務完成,文本通過回調返回。 |
close(code?: number, reason?: string) | void | 關閉連接並釋放任務資源。 |
回調事件
通過 on(event, listener) 註冊回調;完整事件字段見服務端事件。
| 事件 | 負載 | 說明 |
|---|---|---|
started | { taskId: string } | 任務已啓動,可發送輸入。 |
result | { text: string; sentence_end: boolean; sentence_begin?: boolean; words?: RecognitionWord[] } | 中間或最終句子,已過濾心跳結果。 |
sentenceEnd | { text: string; sentence_end: boolean; sentence_begin?: boolean; words?: RecognitionWord[] } | 最終句子,sentence_end === true。 |
finished | { taskId: string; duration?: number; usage?: RecognitionUsage } | 任務已結束,本地任務狀態已清理。 |
failed / error | DashScopeError | 調用錯誤,包含 code、message 和請求標識。 |
close | { code: number; reason: string } | 底層連接關閉通知。 |
event | ServerEvent | 原始服務端 JSON 消息。 |
Qwen-Audio-ASR-Message
主要方法
| 方法 | 返回值 | 說明 |
|---|---|---|
start() | Promise<void> | 啓動識別任務,完成後可發送音頻。 |
sendAudio(audio: Buffer | Uint8Array) | void | 按配置的格式和採樣率發送音頻幀。 |
updateContext(context: AsrContextMessage[]) | void | 在任務啓動後、結束輸入前更新識別上下文。 |
finish() | Promise<void> | 結束音頻輸入並等待任務完成,文本通過回調返回。 |
close(code?: number, reason?: string) | void | 關閉連接並釋放任務資源。 |
回調事件
通過 on(event, listener) 註冊回調;完整事件字段見服務端事件。
| 事件 | 負載 | 說明 |
|---|---|---|
started | { taskId: string } | 任務已啓動,可發送輸入。 |
result | { text: string; sentence_end: boolean; sentence_begin?: boolean; words?: RecognitionWord[] } | 中間或最終句子,已過濾心跳結果。 |
sentenceEnd | { text: string; sentence_end: boolean; sentence_begin?: boolean; words?: RecognitionWord[] } | 最終句子,sentence_end === true。 |
finished | { taskId: string; duration?: number; usage?: RecognitionUsage } | 任務已結束,本地任務狀態已清理。 |
failed / error | DashScopeError | 調用錯誤,包含 code、message 和請求標識。 |
close | { code: number; reason: string } | 底層連接關閉通知。 |
event | ServerEvent | 原始服務端 JSON 消息。 |