透過 HTTP 將完整文字轉換為語音,了解模型特性、快速呼叫方法和合成效果最佳化方式。
功能介紹
非即時語音合成透過 HTTP 一次提交完整文字,支援非串流和 SSE 串流輸出。非串流在合成完成後傳回完整音訊,串流逐段傳回音訊資料。
- 多語言與方言:根據目標語言選擇模型和音色,也可透過指令指定方言。參見方言。
- 表現力控制:透過自然語言指令調整語速、情感等表達,或在文字中插入情感與副語言標籤。參見指令控制和情感與副語言標籤。
- 自訂音色:透過音色複刻從音訊樣本建立音色,或透過音色設計使用文字描述建立音色。
- 精細控制與公式朗讀:使用 SSML 與 LaTeX控制停頓、發音等效果,或將公式轉換為語音。
說明
- 各模型及音色支援的能力有所不同,使用前請核對對應功能的支援範圍。
- 需要分批輸入文字時,請使用即時語音合成。
開始使用
在主控台取得 API Key,並將其設定為環境變數 DASHSCOPE_API_KEY。
安裝範例相依套件:
pip install requests
Qwen-Audio-TTS(推薦)
以下使用新加坡地區的 qwen-audio-3.1-tts-flash 和系統音色 longanhuan_v3.1,示範非串流和串流輸出。
非串流輸出
import os
import requests
response = requests.post(
'https://{WorkspaceId}.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://{WorkspaceId}.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
以下使用北京地區的 cosyvoice-v3-flash 和系統音色 longanyang,示範非串流和串流輸出。
非串流輸出
import os
import requests
response = requests.post(
'https://{WorkspaceId}.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://{WorkspaceId}.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
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 設定自然語言指令。
建議在 instruction 中說明合成語種和所需效果,以提升合成品質。指令中指定的語種須與待合成文字的語種一致。例如,合成荷蘭語文字時,可設定:
{"instruction": "请用荷兰话说,每个字都慢慢说"}
CosyVoice
說明CosyVoice 的 instruction 長度不得超過 100 個字元。計數時,漢字(包括簡體、繁體漢字、日文漢字和韓文漢字)按 2 個字元計算,其他字元(包括標點符號、字母、數字、假名和諺文)按 1 個字元計算。
| 模型 | 可使用的音色 | 指令要求 | 指令文字語言 |
|---|---|---|---|
cosyvoice-v3.5-plus、cosyvoice-v3.5-flash | 複製音色、設計音色 無系統音色。 | 自然語言指令。 | 中文、英文、法文、德文、日文、韓文、俄文、葡萄牙文、泰文、印尼文、越南文。 |
cosyvoice-v3-plus | 系統音色 | 按音色清單中的固定格式和內容填寫。 複製音色、設計音色不支援指令控制。 | 依音色清單指定的語言填寫。 |
cosyvoice-v3-flash | 系統音色 | 按音色清單中的固定格式和內容填寫。 | 中文。 |
複製音色、設計音色 | 自然語言指令。 | 中文、英文、法文、德文、日文、韓文、俄文。 |
方言
透過方言功能,可將文字合成為河南話、四川話等中文方言語音。方言的選擇方式取決於模型和音色類型。
Qwen-Audio-TTS
- 系統音色:從 Qwen-Audio-TTS 音色清單中選擇支援目標方言的音色。直接支援該方言的音色無需額外設定;支援方言指令的音色使用指令控制參數
instruction指定。 - 複製音色:透過指令控制參數
instruction指定方言。 - 設計音色:暫不支援方言。
對於支援方言指令的音色,在請求的 input 中設定 instruction="请讲上海话。",可將中文文字合成為上海話。
CosyVoice
- 系統音色:選擇直接支援目標方言的音色,例如
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]好了,现在让我们开始吧!
支援標籤
控制類標籤
控制類標籤設定後續文字的情感或風格,直到出現下一個控制類標籤;長句被自動切分時,作用範圍以切分後的文字為界。
| 標籤 | 說明 |
|---|---|
| 悲傷 |
| 驚嘆 |
| 深沉大聲吶喊 |
| 顫抖 |
| 憤怒 |
| 興奮 |
| 諷刺 |
| 好奇 |
| 吸血鬼語氣 |
| 無聊 |
| 疲倦 |
| 輕蔑 |
| 大喊 |
| ASMR 輕聲 |
| 驚慌 |
| 調皮 |
| 共情 |
| 低聲耳語 |
| 不情願 |
| 哭泣 |
| 嚴肅 |
| 非常緩慢 |
| 非常快速 |
副語言標籤
副語言標籤在目前位置插入擬聲效果,不改變前後文字的情感風格。
| 標籤 | 說明 |
|---|---|
| 倒吸氣 |
| 嘆息 |
| 清嗓 |
| 咯咯笑 |
| 大笑 |
| 咳嗽 |
| 哼聲、嗤笑 |
應用於生產環境
音訊下載與儲存、格式與播放器相容性、並行管理和問題排查,請參見語音合成最佳實務。請求頻率和並行數應遵循對應模型的限流。
支援模型
新加坡
- 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
華北 2(北京)
- 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
- CosyVoice:cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-plus、cosyvoice-v3-flash、cosyvoice-v2
- Qwen3-TTS:qwen3-tts-flash
系統音色與試聽分別參見 Qwen-Audio-TTS、CosyVoice和 Qwen3-TTS 音色清單。使用複製或設計音色時,合成模型須與建立音色時指定的目標模型一致。