全部產品
Search
文件中心

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

更新時間:Nov 19, 2026

通過語音 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 的構造參數如下。

參數

類型

必填

說明

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-tts-flash。

voice

string

是

音色 ID,使用與模型匹配的音色。

format

'pcm' | 'wav' | 'mp3' | 'opus'

否

音頻編碼格式。省略時使用服務端默認值。

sampleRate

8000 | 16000 | 22050 | 24000 | 44100 | 48000

否

音頻採樣率(Hz),與編碼格式匹配;省略時由服務端決定。

volume

number

否

音量,範圍 [0,100],服務端默認 50。

rate

number

否

語速,範圍 [0.5,2.0],服務端默認 1.0。

pitch

number

否

音調,範圍 [0.5,2.0],服務端默認 1.0。

wordTimestampEnabled

boolean

否

是否返回字級時間戳,默認 false。

languageHints

string[]

否

說明使用 qwen-audio-3.1-tts-flash 的多語種與方言音色時,可透過此參數指定語種或方言。具體用法請參見多語種與方言音色的設定方法。

目標語言提示,當前僅第一個元素生效。

instruction

string

否

方言、情感或角色等合成指令。

parameters

TtsSynthesisParameters

否

其他合成參數,如 enable_ssml、seed 和 hot_fix。

connectTimeoutMs

number

否

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

taskTimeoutMs

number

否

任務啓動或結束的等待超時(ms),默認 60000;0 表示不限制。

parameters.enable_ssml

boolean

否

開啓 SSML。一次任務只發送一次完整的非空 SSML 文本;使用限制。

parameters.bit_rate

number

否

MP3/Opus 碼率(kbps),參數範圍 [6,510],默認 32。

parameters.seed

number

否

隨機種子,範圍 [0,65535]。

parameters.hot_fix

Record<string, unknown>

否

熱修復配置,通過 parameters.hot_fix 傳入;結構見客戶端事件。

parameters.enable_markdown_filter

boolean

否

是否啟用 Markdown 過濾。啟用後,服務會在合成前將 Markdown 轉換為適合朗讀的文字。

預設值:false。設為 true 即可啟用。

介面參考

主要方法

方法

返回值

說明

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 }

任務已啓動,可發送輸入。

audio

Buffer

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

sentenceBegin

{ index: number; text: string }

開始合成一個句子。

sentenceEnd

{ index: number; text: string; characters?: number; words?: TtsWord[]; usage?: TtsUsage }

句子合成完成;可獲取字級時間戳及原始用量。

finished

{ taskId: string; characters?: number; usage?: TtsUsage }

任務已結束,本地任務狀態已清理。

failed / error

DashScopeError

調用錯誤,包含 code、message 和請求標識。

close

{ code: number; reason: string }

底層連接關閉通知。

event

ServerEvent

原始服務端 JSON 消息。