Skip to main content

Qwen-Audio-TTS Node.js SDK

通過語音 Node.js SDK 調用 Qwen-Audio-TTS,使用一次性或流式文本輸入生成音頻,並處理字級時間戳和用量事件。

前提條件

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

安裝 SDK

需要 Node.js 18 或以上版本。下載 SDK 0.1.0 安裝包後,在項目目錄運行:
npm install ./dashscope-sdk-nodejs-0.1.0.tgz

快速開始

將以下示例保存為 example.mjs,運行 node example.mjs。
import { writeFile } from 'node:fs/promises'
import { SpeechSynthesizer } from 'dashscope-sdk-nodejs/tts'

const synth = new SpeechSynthesizer({
  apiKey: process.env.DASHSCOPE_API_KEY,
  workspaceId: process.env.DASHSCOPE_WORKSPACE_ID,
  baseUrl: 'dashscope-intl.aliyuncs.com',
  model: 'qwen-audio-3.1-tts-flash',
  voice: 'longanhuan_v3.1',
  format: 'mp3',
  sampleRate: 24000,
})
synth.on('error', err => console.error(err.code, err.message))

try {
  const audio = await synth.synthesize('Hello, welcome to Qwen Audio.')
  await writeFile('output.mp3', audio)
} finally {
  synth.close()
}

請求參數

SpeechSynthesizer 的構造參數如下。
參數類型必填說明
apiKeystring否API Key。默認讀取 DASHSCOPE_API_KEY。
workspaceIdstring否業務空間 ID。默認讀取 DASHSCOPE_WORKSPACE_ID。
baseUrlstring否服務域名,設置為 dashscope-intl.aliyuncs.com(新加坡)。
modelstring否模型 ID。默認 qwen-audio-3.1-tts-flash。
voicestring是音色 ID,使用與模型匹配的音色。
format'pcm' | 'wav' | 'mp3' | 'opus'否音頻編碼格式。省略時使用服務端默認值。
sampleRate8000 | 16000 | 22050 | 24000 | 44100 | 48000否音頻採樣率(Hz),與編碼格式匹配;省略時由服務端決定。
volumenumber否音量,範圍 [0,100],服務端默認 50。
ratenumber否語速,範圍 [0.5,2.0],服務端默認 1.0。
pitchnumber否音調,範圍 [0.5,2.0],服務端默認 1.0。
wordTimestampEnabledboolean否是否返回字級時間戳,默認 false。
languageHintsstring[]否
使用 qwen-audio-3.1-tts-flash 的多語種與方言音色時,可透過此參數指定語種或方言。具體用法請參見多語種與方言音色的設定方法。
目標語言提示,當前僅第一個元素生效。
instructionstring否方言、情感或角色等合成指令。
parametersTtsSynthesisParameters否其他合成參數,如 enable_ssml、seed 和 hot_fix。
connectTimeoutMsnumber否建連超時(ms),默認 10000。
taskTimeoutMsnumber否任務啓動或結束的等待超時(ms),默認 60000;0 表示不限制。
parameters.enable_ssmlboolean否開啓 SSML。一次任務只發送一次完整的非空 SSML 文本;使用限制。
parameters.bit_ratenumber否MP3/Opus 碼率(kbps),參數範圍 [6,510],默認 32。
parameters.seednumber否隨機種子,範圍 [0,65535]。
parameters.hot_fixRecord<string, unknown>否熱修復配置,通過 parameters.hot_fix 傳入;結構見客戶端事件。

介面參考

主要方法

方法返回值說明
synthesize(text: string)Promise<Buffer>合成完整文本並返回音頻,文本最多 20000 字符。
begin()Promise<void>啓動流式合成任務,完成後可發送文本。
sendText(text: string)void發送文本片段;每次最多 20000 字符,單任務累計最多 200000 字符。
end()Promise<Buffer>結束文本輸入,等待合成完成並返回完整音頻。
cancel()void發送取消合成的請求。
close(code?: number, reason?: string)void關閉連接並釋放任務資源。

回調事件

通過 on(event, listener) 註冊回調;完整事件字段見服務端事件。
事件負載說明
started{ taskId: string }任務已啓動,可發送輸入。
audioBuffer音頻二進制塊,可多次觸發。
sentenceBegin{ index: number; text: string }開始合成一個句子。
sentenceEnd{ index: number; text: string; characters?: number; words?: TtsWord[]; usage?: TtsUsage }句子合成完成;可獲取字級時間戳及原始用量。
finished{ taskId: string; characters?: number; usage?: TtsUsage }任務已結束,本地任務狀態已清理。
failed / errorDashScopeError調用錯誤,包含 code、message 和請求標識。
close{ code: number; reason: string }底層連接關閉通知。
eventServerEvent原始服務端 JSON 消息。