Skip to main content
QwenCloud home page
Docs
SDK access

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.

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,
  // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
  // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
  baseUrl: 'ap-southeast-1.maas.qwencloudapi.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:
ParameterTypeRequiredDescription
apiKeystringNoAPI key. Defaults to DASHSCOPE_API_KEY.
baseUrlstringNoSet the service hostname to ap-southeast-1.maas.qwencloudapi.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[]NoTarget-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.

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.