全部產品
Search
文件中心

Alibaba Cloud Model Studio:Qwen-Audio-Realtime Node.js SDK

更新時間:Nov 11, 2026

通過語音 Node.js SDK 調用 Qwen-Audio-Realtime,配置會話、收發音頻、處理轉寫和工具調用。

安裝 SDK

需要 Node.js 18 或以上版本。下載 SDK 0.1.0 安裝包後,在項目目錄運行:

npm install ./dashscope-sdk-nodejs-0.1.0.tgz

快速開始

在控制台獲取 API Key,並配置為環境變量 DASHSCOPE_API_KEY。

下載示例音頻,保存為 input.mp3,並轉換為 16 kHz、16-bit、單聲道 PCM:

ffmpeg -i input.mp3 -f s16le -ac 1 -ar 16000 input.pcm

將以下示例保存為 example.mjs,運行 node example.mjs。

import { readFileSync, writeFileSync } from 'node:fs'
import { setTimeout as sleep } from 'node:timers/promises'
import { RealtimeClient } from 'dashscope-sdk-nodejs/realtime'

const pcm = readFileSync('input.pcm')
const client = new RealtimeClient({
  apiKey: process.env.DASHSCOPE_API_KEY,
  workspaceId: process.env.DASHSCOPE_WORKSPACE_ID,
  baseUrl: 'dashscope-intl.aliyuncs.com',
  model: 'qwen-audio-3.1-realtime-plus',
  voice: 'longanqian_v3.1',
  turnDetection: null,
  inputTranscription: { language: 'zh' },
})
const audio = []
function fail(err) {
  console.error(err.code, err.message)
  process.exitCode = 1
  client.close()
}
const timer = setTimeout(() => fail(new Error('Response timed out')), 60000)
client.on('close', () => clearTimeout(timer))
client.on('error', fail)
client.on('audio', chunk => audio.push(chunk))
client.on('inputTranscript', ({ transcript }) => console.log('User:', transcript))
client.on('outputTranscript', ({ transcript }) => console.log('Assistant:', transcript))
client.once('sessionUpdated', () => {
  ;(async () => {
    for (let offset = 0; offset < pcm.length; offset += 3200) {
      client.appendAudio(pcm.subarray(offset, offset + 3200))
      await sleep(100)
    }
    client.commit()
    client.createResponse()
  })().catch(fail)
})
client.once('responseDone', event => {
  if (event.response?.status !== 'completed') {
    fail(new Error('Response status: ' + event.response?.status))
    return
  }
  writeFileSync('output.pcm', Buffer.concat(audio))
  client.close()
})
try {
  await client.connect()
} catch (err) {
  fail(err)
}

接口參考

構造參數

RealtimeClient 的構造參數如下。

參數

類型

必填

說明

apiKey

string

否

API Key。默認讀取 DASHSCOPE_API_KEY。

workspaceId

string

否

業務空間 ID。默認讀取 DASHSCOPE_WORKSPACE_ID。

baseUrl

string

否

服務域名,設置為 dashscope-intl.aliyuncs.com(新加坡)。

model

string

是

模型 ID。

voice

string

否

音色 ID。省略時使用服務端默認音色。

instructions

string

否

系統指令,設置角色、風格等。

turnDetection

TurnDetection | null

否

默認 { type: "server_vad" };null 表示手動提交;可使用 smart_turn 或 smart_turn_v2。

modalities

Array<'text' | 'audio'>

否

輸出模態,默認 ["text", "audio"]。

maxHistoryTurns

number

否

歷史輪數,範圍 [1,50],服務端默認 20。

tools

ToolDefinition[]

否

工具定義;應用執行工具並校驗參數。

inputTranscription

{ model?: string; language?: string } | null

否

輸入音頻轉寫配置,如 { model: "fun-asr", language: "zh" };null 關閉轉寫。

sessionExtras

SessionConfig

否

擴展會話參數,如 speech_rate、enable_search;覆蓋對應的頂層配置,字段見客戶端事件。

connectTimeoutMs

number

否

建連超時(ms),默認 10000。

主要方法

方法

返回值

說明

connect()

Promise<void>

建立連接併發送會話配置,通過 sessionUpdated 確認配置生效。

updateSession(session: SessionConfig)

void

更新會話參數,通過 sessionUpdated 確認生效。

appendAudio(pcm: Buffer | Uint8Array)

void

發送 16 kHz、16-bit、單聲道 PCM 音頻。

commit()

void

手動模式下提交音頻緩衝區。

clearAudioBuffer()

void

清空尚未提交的音頻緩衝區。

createResponse(response?: Record<string, unknown>)

void

請求模型生成響應。

cancelResponse()

void

取消當前響應,保留會話。

createConversationItem(item: ConversationItem, previousItemId?: string)

void

添加對話歷史或工具結果;previousItemId 指定插入位置。

submitFunctionCallOutput(callId: string, output: string, autoCreateResponse?: boolean)

void

提交工具結果字符串;autoCreateResponse 默認 true,自動請求後續響應。

deleteConversationItem(itemId: string)

void

刪除指定對話項。

retrieveConversationItem(itemId: string)

void

查詢對話項,結果通過 event 回調返回。

sendEvent(event: ClientEvent)

void

發送原始客戶端事件。

close(code?: number, reason?: string)

void

關閉會話和 WebSocket 連接。

回調事件

通過 on(event, listener) 註冊回調;完整事件字段見服務端事件。

事件

負載

說明

open

void

連接已建立、初始配置已發送。

sessionCreated / sessionUpdated

ServerEvent

會話創建或配置確認。

audio

Buffer

音頻二進制塊,可多次觸發。

audioTranscriptDelta

{ delta: string }

輸出音頻轉寫的增量文本。

outputTranscript

{ transcript: string }

輸出音頻的完整轉寫。

textDelta / textDone

{ delta: string } / { text: string }

純文本模態的增量或完整文本。

inputTranscriptDelta

{ text: string; stash: string }

text 是確定文本,stash 是暫存文本;以二者替換當前顯示,而非累計拼接。

inputTranscript

{ transcript: string }

輸入音頻的最終轉寫。

speechStarted / speechStopped

ServerEvent

檢測到用戶語音開始或停止。

responseCreated / responseDone

ServerEvent

響應開始或結束。檢查 responseDone.response.status 是否為 completed,或為取消、失敗狀態。

functionCall

{ callId: string; name: string; arguments: string }

完整工具調用參數;由應用解析並校驗 arguments JSON 字符串。

ambientTranscript / ambientTranscriptCompleted

{ text: string; stash: string } / { transcript: string }

環境音當前或最終轉寫,不寫入會話上下文。

event

ServerEvent

原始服務端 JSON 消息。

error

DashScopeError

連接或服務端錯誤。

close

{ code: number; reason: string }

底層連接關閉通知。