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

Use the speech Node.js SDK to call Qwen-Audio-TTS with complete or streaming text input and handle audio, word timestamps, and usage events.

Install the SDK

Requires Node.js 18 or later. Download the SDK 0.1.0 package, then run this command in your project:

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

Quick start

Obtain an API key in the console and set it as the DASHSCOPE_API_KEY environment variable.

Save the following example as example.mjs and run 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()
}

API reference

Constructor options

Constructor options for SpeechSynthesizer:

Parameter	Type	Required	Description
`apiKey`	`string`	No	API key. Defaults to `DASHSCOPE_API_KEY`.
`workspaceId`	`string`	No	Workspace ID. Defaults to `DASHSCOPE_WORKSPACE_ID`.
`baseUrl`	`string`	No	Set the service hostname to `dashscope-intl.aliyuncs.com` (Singapore).
`model`	`string`	No	Model ID. Default: `qwen-audio-3.1-tts-flash`.
`voice`	`string`	Yes	Voice ID. Choose a voice compatible with the model.
`format`	`'pcm' \| 'wav' \| 'mp3' \| 'opus'`	No	Audio encoding. Uses the service default if omitted.
`sampleRate`	`8000 \| 16000 \| 22050 \| 24000 \| 44100 \| 48000`	No	Audio sample rate in Hz. Must match the encoding; uses the service default if omitted.
`volume`	`number`	No	Volume: `[0,100]`. Service default: `50`.
`rate`	`number`	No	Speech rate: `[0.5,2.0]`. Service default: `1.0`.
`pitch`	`number`	No	Pitch: `[0.5,2.0]`. Service default: `1.0`.
`wordTimestampEnabled`	`boolean`	No	Return word timestamps. Default: `false`.
`languageHints`	`string[]`	No	Target-language hints. Only the first element takes effect.
`instruction`	`string`	No	Synthesis instructions for dialect, emotion, or role.
`parameters`	`TtsSynthesisParameters`	No	Additional synthesis parameters, such as `enable_ssml`, `seed`, and `hot_fix`.
`connectTimeoutMs`	`number`	No	Connection timeout in ms. Default: `10000`.
`taskTimeoutMs`	`number`	No	Start/finish acknowledgement timeout in ms. Default: `60000`; `0` disables the timeout.
`parameters.enable_ssml`	`boolean`	No	Enable SSML. Send the complete nonempty SSML text once per task. See limits.
`parameters.bit_rate`	`number`	No	MP3/Opus bit rate in kbps. Parameter range: `[6,510]`; default: `32`.
`parameters.seed`	`number`	No	Random seed: `[0,65535]`.
`parameters.hot_fix`	`Record<string, unknown>`	No	Hot-fix configuration passed as `parameters.hot_fix`. See client events for its structure.

Main methods

Method	Return value	Description
`synthesize(text: string)`	`Promise<Buffer>`	Synthesize complete text and return audio. Up to 20000 characters.
`begin()`	`Promise<void>`	Start a streaming synthesis task, then send text.
`sendText(text: string)`	`void`	Send a text chunk: up to 20000 characters per call and 200000 per task.
`end()`	`Promise<Buffer>`	Finish text input, wait for synthesis, and return the complete audio.
`cancel()`	`void`	Request synthesis cancellation.
`close(code?: number, reason?: string)`	`void`	Close the connection and release task resources.

Callback events

Event	Payload	Description
`started`	`{ taskId: string }`	Task has started and accepts input.
`audio`	`Buffer`	Binary audio chunk; may fire multiple times.
`sentenceBegin`	`{ index: number; text: string }`	Synthesis of a sentence has started.
`sentenceEnd`	`{ index: number; text: string; characters?: number; words?: TtsWord[]; usage?: TtsUsage }`	Sentence synthesis is complete; includes optional word timestamps and raw usage.
`finished`	`{ taskId: string; characters?: number; usage?: TtsUsage }`	Task has finished and local task state is cleared.
`failed / error`	`DashScopeError`	Call error with `code`, `message`, and request identifiers.
`close`	`{ code: number; reason: string }`	Underlying connection-close notification.
`event`	`ServerEvent`	Raw service JSON message.