Skip to main content

Qwen-Audio-TTS Node.js SDK

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

Request parameters

Constructor options for SpeechSynthesizer:
ParameterTypeRequiredDescription
apiKeystringNoAPI key. Defaults to DASHSCOPE_API_KEY.
workspaceIdstringNoWorkspace ID. Defaults to DASHSCOPE_WORKSPACE_ID.
baseUrlstringNoSet the service hostname to dashscope-intl.aliyuncs.com (Singapore).
modelstringNoModel ID. Default: qwen-audio-3.1-tts-flash.
voicestringYesVoice ID. Choose a voice compatible with the model.
format'pcm' | 'wav' | 'mp3' | 'opus'NoAudio encoding. Uses the service default if omitted.
sampleRate8000 | 16000 | 22050 | 24000 | 44100 | 48000NoAudio sample rate in Hz. Must match the encoding; uses the service default if omitted.
volumenumberNoVolume: [0,100]. Service default: 50.
ratenumberNoSpeech rate: [0.5,2.0]. Service default: 1.0.
pitchnumberNoPitch: [0.5,2.0]. Service default: 1.0.
wordTimestampEnabledbooleanNoReturn word timestamps. Default: false.
languageHintsstring[]No
For 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.
instructionstringNoSynthesis instructions for dialect, emotion, or role.
parametersTtsSynthesisParametersNoAdditional synthesis parameters, such as enable_ssml, seed, and hot_fix.
connectTimeoutMsnumberNoConnection timeout in ms. Default: 10000.
taskTimeoutMsnumberNoStart/finish acknowledgement timeout in ms. Default: 60000; 0 disables the timeout.
parameters.enable_ssmlbooleanNoEnable SSML. Send the complete nonempty SSML text once per task. See limits.
parameters.bit_ratenumberNoMP3/Opus bit rate in kbps. Parameter range: [6,510]; default: 32.
parameters.seednumberNoRandom seed: [0,65535].
parameters.hot_fixRecord<string, unknown>NoHot-fix configuration passed as parameters.hot_fix. See client events for its structure.

API reference

Main methods

MethodReturn valueDescription
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)voidSend 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()voidRequest synthesis cancellation.
close(code?: number, reason?: string)voidClose the connection and release task resources.

Callback events

Register callbacks with on(event, listener). See server events for the full event fields.
EventPayloadDescription
started{ taskId: string }Task has started and accepts input.
audioBufferBinary 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 / errorDashScopeErrorCall error with code, message, and request identifiers.
close{ code: number; reason: string }Underlying connection-close notification.
eventServerEventRaw service JSON message.