全部产品
Search
文档中心

大模型服务平台百炼: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 消息。