非即時語音合成

功能介紹

非即時語音合成透過 HTTP 一次提交完整文字，支援非串流和 SSE 串流輸出。非串流傳回的音訊 URL 有效期限為 24 小時，請及時下載儲存；連結過期後可重新合成。串流輸出會逐段傳回音訊資料。

多語言與方言：根據目標語言選擇模型和音色，也可透過指令指定方言。參見方言。
表現力控制：透過自然語言指令調整語速、情感等表達，或在文字中插入情感與副語言標籤。參見指令控制和情感與副語言標籤。
自訂音色：透過聲音複製從音訊樣本建立音色，或透過聲音設計使用文字描述建立音色。
精細控制與公式朗讀：使用 SSML 與 LaTeX控制停頓、發音等效果，或將公式轉換為語音。

各模型及音色支援的能力有所不同，使用前請核對對應功能的支援範圍。
需要分批輸入文字時，請使用即時語音合成。

開始使用

取得 API Key並設定環境變數 DASHSCOPE_API_KEY。使用與範例地區對應的 API Key。
使用業務空間專屬網域時，將程式碼中的 YOUR_WORKSPACE_ID 替換為該地區的業務空間 ID。
安裝範例相依套件：
```
pip install requests
```

Qwen-Audio-TTS（推薦）
CosyVoice

以下使用新加坡地區的 qwen-audio-3.1-tts-flash 和系統音色 longanhuan_v3.1，示範非串流和串流輸出。

非串流輸出
串流輸出

import os
import requests

response = requests.post(
    'https://YOUR_WORKSPACE_ID.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer',
    headers={"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}"},
    json={
        "model": "qwen-audio-3.1-tts-flash",
        "input": {
            "text": "你好，欢迎使用阿里云百炼。",
            "voice": "longanhuan_v3.1",
            "format": "wav",
            "sample_rate": 24000
        }
    },
    timeout=60,
)
response.raise_for_status()
audio_url = response.json()["output"]["audio"]["url"]
audio_response = requests.get(audio_url, timeout=60)
audio_response.raise_for_status()
with open("output.wav", "wb") as f:
    f.write(audio_response.content)

執行後，音訊儲存在目前目錄的 output.wav 檔案中。

以下範例逐行列印 SSE 傳回事件。事件中的 output.audio.data 為 Base64 編碼的音訊片段。

import os
import requests

response = requests.post(
    'https://YOUR_WORKSPACE_ID.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer',
    headers={"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}", "X-DashScope-SSE": "enable"},
    json={
        "model": "qwen-audio-3.1-tts-flash",
        "input": {
            "text": "你好，欢迎使用阿里云百炼。",
            "voice": "longanhuan_v3.1",
            "format": "wav",
            "sample_rate": 24000
        }
    },
    stream=True,
    timeout=60,
)
response.raise_for_status()
for line in response.iter_lines():
    print(line.decode("utf-8"))
response.close()

以下使用北京地區的 cosyvoice-v3-flash 和系統音色 longanyang，示範非串流和串流輸出。

非串流輸出
串流輸出

import os
import requests

response = requests.post(
    'https://YOUR_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer',
    headers={"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}"},
    json={
        "model": "cosyvoice-v3-flash",
        "input": {
            "text": "你好，欢迎使用阿里云百炼。",
            "voice": "longanyang",
            "format": "wav",
            "sample_rate": 24000
        }
    },
    timeout=60,
)
response.raise_for_status()
audio_url = response.json()["output"]["audio"]["url"]
audio_response = requests.get(audio_url, timeout=60)
audio_response.raise_for_status()
with open("output.wav", "wb") as f:
    f.write(audio_response.content)

執行後，音訊儲存在目前目錄的 output.wav 檔案中。

以下範例逐行列印 SSE 傳回事件。事件中的 output.audio.data 為 Base64 編碼的音訊片段。

import os
import requests

response = requests.post(
    'https://YOUR_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer',
    headers={"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}", "X-DashScope-SSE": "enable"},
    json={
        "model": "cosyvoice-v3-flash",
        "input": {
            "text": "你好，欢迎使用阿里云百炼。",
            "voice": "longanyang",
            "format": "wav",
            "sample_rate": 24000
        }
    },
    stream=True,
    timeout=60,
)
response.raise_for_status()
for line in response.iter_lines():
    print(line.decode("utf-8"))
response.close()

合成效果最佳化

語言與發音

數字、縮寫或符號的讀法不符合預期時，可透過 language_hints 指定合成目標語言，或透過 hot_fix 定義詞語發音與文字替換。參數適用模型和設定方法請參見對應的 Qwen-Audio-TTS API或 CosyVoice API。需要控制停頓、數字讀法或字詞發音時，可使用 SSML。Qwen-Audio-TTS 和 CosyVoice 的適用模型、音色、介面與標籤用法，請參見 SSML 與 LaTeX。

指令控制

在請求的 input 中新增 instruction，以自然語言描述語速、情感或說話方式，控制合成語音的表現。

如需建立具有特定性別、年齡或音色特質的新音色，或參考聲音描述的撰寫建議與範例，請參見聲音設計。

Qwen-Audio-TTS
CosyVoice

qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash 的系統音色、複製音色和設計音色均支援在合成請求中透過 instruction 設定自然語言指令。在 Qwen-Audio-TTS 的開始使用範例中，為 input 增加以下欄位，可放慢語速：

{"instruction": "请用非常缓慢的语速说话，每个字都慢慢说。"}

CosyVoice 的 instruction 長度不得超過 100 個字元。計數時，漢字（包括簡體、繁體漢字、日文漢字和韓文漢字）按 2 個字元計算，其他字元（包括標點符號、字母、數字、假名和諺文）按 1 個字元計算。

模型	可使用的音色	指令要求	指令文字語言
`cosyvoice-v3.5-plus`、`cosyvoice-v3.5-flash`	複製音色、設計音色無系統音色。	自然語言指令。	中文、英文、法文、德文、日文、韓文、俄文、葡萄牙文、泰文、印尼文、越南文。
`cosyvoice-v3-plus`	系統音色	按音色清單中的固定格式和內容填寫。複製音色、設計音色不支援指令控制。	依音色清單指定的語言填寫。
`cosyvoice-v3-flash`	系統音色	按音色清單中的固定格式和內容填寫。	中文。
`cosyvoice-v3-flash`	複製音色、設計音色	自然語言指令。	中文、英文、法文、德文、日文、韓文、俄文。

方言

透過方言功能，可將文字合成為河南話、四川話等中文方言語音。方言的選擇方式取決於模型和音色類型。

Qwen-Audio-TTS
CosyVoice

系統音色：從 Qwen-Audio-TTS 音色清單中選擇支援目標方言的音色。直接支援該方言的音色無需額外設定；支援方言指令的音色使用 instruction 指定。
複製音色：透過 instruction 指定方言，例如 请用河南话表达。。
設計音色：暫不支援方言。

系統音色：選擇直接支援目標方言的音色，例如 longshange_v3；或選擇支援方言指令的音色，例如 longanhuan_v3，依音色清單的格式填寫指令。
複製音色：使用支援指令控制的模型，透過 instruction 指定方言。
設計音色：暫不支援方言。

cosyvoice-v3-plus 的複製音色不支援透過指令指定方言。

使用 CosyVoice 的開始使用範例時，將 input 替換為以下內容，可使用 longanhuan_v3 輸出河南話：

{
  "text": "叫你去买盐，你买回来一袋面，这不是弄啥嘞吗！",
  "voice": "longanhuan_v3",
  "format": "wav",
  "sample_rate": 24000,
  "instruction": "请用河南话表达。"
}

Qwen3-TTS 使用支援目標方言的系統音色，參見 Qwen3-TTS 音色清單。

情感與副語言標籤

適用於 qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus 和 qwen-audio-3.0-tts-flash。

情感與富語言標籤可控制語音的情感和風格，並在指定位置加入笑聲、嘆息等擬聲效果。將標籤直接寫入待合成文字 text，無需額外參數。

使用範例

以下文字先使用興奮語氣，在指定位置插入笑聲後繼續合成正文：

[excited]今天的天气真不错！[laughing]我们一起出去玩吧！

以下文字在第二句切換為興奮語氣：

[serious]请注意安全事项。[excited]好了，现在让我们开始吧！

支援標籤

控制類標籤
副語言標籤

控制類標籤設定後續文字的情感或風格，直到出現下一個控制類標籤；長句被自動切分時，作用範圍以切分後的文字為界。

標籤	說明
`[sad]`	悲傷
`[amazed]`	驚嘆
`[deep and loud shouting]`	深沉大聲吶喊
`[trembling]`	顫抖
`[angry]`	憤怒
`[excited]`	興奮
`[sarcastic]`	諷刺
`[curious]`	好奇
`[like dracula]`	吸血鬼語氣
`[bored]`	無聊
`[tired]`	疲倦
`[scornful]`	輕蔑
`[shouting]`	大喊
`[asmr]`	ASMR 輕聲
`[panicked]`	驚慌
`[mischievously]`	調皮
`[empathetic]`	共情
`[whispers]`	低聲耳語
`[reluctantly]`	不情願
`[crying]`	哭泣
`[serious]`	嚴肅
`[very slowly]`	非常緩慢
`[very fast]`	非常快速

副語言標籤在目前位置插入擬聲效果，不改變前後文字的情感風格。

標籤	說明
`[gasp]`	倒吸氣
`[sighing]`	嘆息
`[clears throat]`	清嗓
`[giggles]`	咯咯笑
`[laughing]`	大笑
`[cough]`	咳嗽
`[snorts]`	哼聲、嗤笑

支援模型

新加坡
華北 2（北京）

使用該地區的 API Key 和接入網域呼叫以下模型：

Qwen-Audio-TTS：qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash
Qwen3-TTS：qwen3-tts-flash

系統音色與試聽分別參見 Qwen-Audio-TTS、CosyVoice和 Qwen3-TTS 音色清單。使用複製或設計音色時，合成模型須與建立音色時指定的目標模型一致。

​功能介紹

​開始使用

​合成效果最佳化

​語言與發音

​指令控制

​方言

​情感與副語言標籤

​使用範例

​支援標籤

​支援模型

​API 參考

功能介紹

開始使用

合成效果最佳化

語言與發音

指令控制

方言

情感與副語言標籤

使用範例

支援標籤

支援模型

API 參考