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:
Quick start
Save the following example as example.mjs and run node example.mjs.
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 | 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 | 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. |
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. |
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. |