通過語音 Node.js SDK 調用 Qwen-Audio-TTS,使用一次性或流式文本輸入生成音頻,並處理字級時間戳和用量事件。
前提條件
在控制台獲取 API Key,並配置為環境變量 DASHSCOPE_API_KEY。
安裝 SDK
需要 Node.js 18 或以上版本。下載 SDK 0.1.0 安裝包後,在項目目錄運行:
快速開始
將以下示例保存為 example.mjs,運行 node example.mjs。
請求參數
SpeechSynthesizer 的構造參數如下。
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
apiKey | string | 否 | API Key。默認讀取 DASHSCOPE_API_KEY。 |
workspaceId | string | 否 | 業務空間 ID。默認讀取 DASHSCOPE_WORKSPACE_ID。 |
baseUrl | string | 否 | 服務域名,設置為 dashscope-intl.aliyuncs.com(新加坡)。 |
model | string | 否 | 模型 ID。默認 qwen-audio-3.1-tts-flash。 |
voice | string | 是 | 音色 ID,使用與模型匹配的音色。 |
format | 'pcm' | 'wav' | 'mp3' | 'opus' | 否 | 音頻編碼格式。省略時使用服務端默認值。 |
sampleRate | 8000 | 16000 | 22050 | 24000 | 44100 | 48000 | 否 | 音頻採樣率(Hz),與編碼格式匹配;省略時由服務端決定。 |
volume | number | 否 | 音量,範圍 [0,100],服務端默認 50。 |
rate | number | 否 | 語速,範圍 [0.5,2.0],服務端默認 1.0。 |
pitch | number | 否 | 音調,範圍 [0.5,2.0],服務端默認 1.0。 |
wordTimestampEnabled | boolean | 否 | 是否返回字級時間戳,默認 false。 |
languageHints | string[] | 否 | 使用 qwen-audio-3.1-tts-flash 的多語種與方言音色時,可透過此參數指定語種或方言。具體用法請參見多語種與方言音色的設定方法。 |
instruction | string | 否 | 方言、情感或角色等合成指令。 |
parameters | TtsSynthesisParameters | 否 | 其他合成參數,如 enable_ssml、seed 和 hot_fix。 |
connectTimeoutMs | number | 否 | 建連超時(ms),默認 10000。 |
taskTimeoutMs | number | 否 | 任務啓動或結束的等待超時(ms),默認 60000;0 表示不限制。 |
parameters.enable_ssml | boolean | 否 | 開啓 SSML。一次任務只發送一次完整的非空 SSML 文本;使用限制。 |
parameters.bit_rate | number | 否 | MP3/Opus 碼率(kbps),參數範圍 [6,510],默認 32。 |
parameters.seed | number | 否 | 隨機種子,範圍 [0,65535]。 |
parameters.hot_fix | Record<string, unknown> | 否 | 熱修復配置,通過 parameters.hot_fix 傳入;結構見客戶端事件。 |
介面參考
主要方法
| 方法 | 返回值 | 說明 |
|---|---|---|
synthesize(text: string) | Promise<Buffer> | 合成完整文本並返回音頻,文本最多 20000 字符。 |
begin() | Promise<void> | 啓動流式合成任務,完成後可發送文本。 |
sendText(text: string) | void | 發送文本片段;每次最多 20000 字符,單任務累計最多 200000 字符。 |
end() | Promise<Buffer> | 結束文本輸入,等待合成完成並返回完整音頻。 |
cancel() | void | 發送取消合成的請求。 |
close(code?: number, reason?: string) | void | 關閉連接並釋放任務資源。 |
回調事件
通過 on(event, listener) 註冊回調;完整事件字段見服務端事件。
| 事件 | 負載 | 說明 |
|---|---|---|
started | { taskId: string } | 任務已啓動,可發送輸入。 |
audio | Buffer | 音頻二進制塊,可多次觸發。 |
sentenceBegin | { index: number; text: string } | 開始合成一個句子。 |
sentenceEnd | { index: number; text: string; characters?: number; words?: TtsWord[]; usage?: TtsUsage } | 句子合成完成;可獲取字級時間戳及原始用量。 |
finished | { taskId: string; characters?: number; usage?: TtsUsage } | 任務已結束,本地任務狀態已清理。 |
failed / error | DashScopeError | 調用錯誤,包含 code、message 和請求標識。 |
close | { code: number; reason: string } | 底層連接關閉通知。 |
event | ServerEvent | 原始服務端 JSON 消息。 |