Qwen-Audio-TTS Node.js SDK

Updated at:

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.

Prerequisites

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

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

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.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()
}

Request parameters

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

Service hostname. Default: dashscope.aliyuncs.com (Beijing).

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

NoteFor the multilingual and dialect voices of qwen-audio-3.1-tts-flash, this parameter specifies the language or dialect. See multilingual and dialect voice settings for details.

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.

parameters.enable_markdown_filter

boolean

No

Whether to enable Markdown filtering. When enabled, the service converts Markdown into text suitable for reading aloud before synthesis.

Default: false. Set to true to enable.

API reference

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

Register callbacks with on(event, listener). See server events for the full event fields.

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.