了解即時語音合成的模型特性、串流呼叫方法和合成效果最佳化方式。
功能介紹
即時語音合成支援分段輸入文字、逐段傳回音訊,適合將大模型產生的文字即時轉換為語音。
- 多語言與方言:根據目標語言選擇模型和音色,也可透過指令指定方言。參見方言。
- 表現力控制:透過自然語言指令調整語速、情感等表達,或在文字中插入情感與副語言標籤。參見指令控制和情感與副語言標籤。
- 自訂音色:透過音色複刻從音訊樣本建立音色,或透過音色設計使用文字描述建立音色。
- 精細控制與公式朗讀:使用 SSML 與 LaTeX控制停頓、發音等效果,或將公式轉換為語音。
- 音訊控制:可調節語速、語調、音量和位元速率,輸出 PCM、WAV、MP3、Opus 等主流音訊格式,最高支援 48 kHz 取樣率。具體取值與支援範圍以對應 API 參數說明為準。
說明各模型及音色支援的能力有所不同,使用前請核對對應功能的支援範圍。
需要透過 HTTP 一次提交完整文字時,請參見非即時語音合成。
開始使用
安裝 DashScope SDK,在主控台取得 API Key,並設定 DASHSCOPE_API_KEY 環境變數。
Qwen-Audio-TTS(推薦)
以下使用北京地區的 qwen-audio-3.1-tts-flash 和系統音色 longanhuan_v3.1,分段傳送文字並將傳回音訊儲存為 output.mp3。
import com.alibaba.dashscope.audio.tts.SpeechSynthesisResult;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisAudioFormat;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;
import java.io.FileOutputStream;
import java.nio.ByteBuffer;
public class Main {
public static void main(String[] args) throws Exception {
Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
try (FileOutputStream audio = new FileOutputStream("output.mp3")) {
SpeechSynthesisParam param = SpeechSynthesisParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("qwen-audio-3.1-tts-flash")
.voice("longanhuan_v3.1")
.format(SpeechSynthesisAudioFormat.MP3_24000HZ_MONO_256KBPS)
.build();
ResultCallback<SpeechSynthesisResult> callback = new ResultCallback<>() {
@Override
public void onEvent(SpeechSynthesisResult result) {
ByteBuffer buffer = result.getAudioFrame();
if (buffer != null) {
byte[] bytes = new byte[buffer.remaining()];
buffer.get(bytes);
try { audio.write(bytes); }
catch (Exception e) { throw new RuntimeException(e); }
}
}
@Override
public void onComplete() {}
public void onError(Exception e) { e.printStackTrace(); }
};
SpeechSynthesizer synthesizer = new SpeechSynthesizer(param, callback);
try {
for (String text : new String[]{"你好,欢迎使用阿里云百炼。", "文本可以分段发送,音频会逐段返回。"}) {
synthesizer.streamingCall(text);
}
synthesizer.streamingComplete(60000);
} finally {
synthesizer.getDuplexApi().close(1000, "done");
}
}
}
}
import os
import dashscope
# 若沒有配置環境變數,請將下行替換為您的百鍊API Key:api_key="sk-xxx"
# 以下為中國(北京)地區的配置。呼叫時請將"{WorkspaceId}"替換為真實的業務空間ID。
client = dashscope.Client(
api_key=os.environ["DASHSCOPE_API_KEY"],
workspace="{WorkspaceId}",
region="cn-beijing",
)
with open("output.mp3", "wb") as audio:
# 分段發送文本,逐段接收音頻
with client.audio.tts.connect(
model="qwen-audio-3.1-tts-flash",
voice="longanhuan_v3.1",
format="mp3",
sample_rate=24000,
) as session:
for text in ["你好,欢迎使用阿里云百炼。", "文本可以分段发送,音频会逐段返回。"]:
session.send_text(text)
session.flush() # 觸發緩衝文本的合成(不結束輸入)
session.stop() # 結束輸入並等待剩餘音頻返回
for chunk in session.audio_chunks():
audio.write(chunk)
CosyVoice
以下使用北京地區的 cosyvoice-v3-flash 和系統音色 longanyang,分段傳送文字並將傳回音訊儲存為 output.mp3。
import com.alibaba.dashscope.audio.tts.SpeechSynthesisResult;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisAudioFormat;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;
import java.io.FileOutputStream;
import java.nio.ByteBuffer;
public class Main {
public static void main(String[] args) throws Exception {
Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
try (FileOutputStream audio = new FileOutputStream("output.mp3")) {
SpeechSynthesisParam param = SpeechSynthesisParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("cosyvoice-v3-flash")
.voice("longanyang")
.format(SpeechSynthesisAudioFormat.MP3_24000HZ_MONO_256KBPS)
.build();
ResultCallback<SpeechSynthesisResult> callback = new ResultCallback<>() {
@Override
public void onEvent(SpeechSynthesisResult result) {
ByteBuffer buffer = result.getAudioFrame();
if (buffer != null) {
byte[] bytes = new byte[buffer.remaining()];
buffer.get(bytes);
try { audio.write(bytes); }
catch (Exception e) { throw new RuntimeException(e); }
}
}
@Override
public void onComplete() {}
public void onError(Exception e) { e.printStackTrace(); }
};
SpeechSynthesizer synthesizer = new SpeechSynthesizer(param, callback);
try {
for (String text : new String[]{"你好,欢迎使用阿里云百炼。", "文本可以分段发送,音频会逐段返回。"}) {
synthesizer.streamingCall(text);
}
synthesizer.streamingComplete(60000);
} finally {
synthesizer.getDuplexApi().close(1000, "done");
}
}
}
}
import os
import dashscope
# 若沒有配置環境變數,請將下行替換為您的百鍊API Key:api_key="sk-xxx"
client = dashscope.Client(
api_key=os.environ["DASHSCOPE_API_KEY"],
workspace="{WorkspaceId}",
region="cn-beijing",
)
with open("output.mp3", "wb") as audio:
# 分段發送文本,逐段接收音頻
with client.audio.tts.connect(
model="cosyvoice-v3-flash",
voice="longanyang",
format="mp3",
sample_rate=24000,
) as session:
for text in ["你好,欢迎使用阿里云百炼。", "文本可以分段发送,音频会逐段返回。"]:
session.send_text(text)
session.flush() # 觸發緩衝文本的合成(不結束輸入)
session.stop() # 結束輸入並等待剩餘音頻返回
for chunk in session.audio_chunks():
audio.write(chunk)
合成效果最佳化
語言與發音
根據需要控制的內容,選擇對應方式:
| 需求 | 使用方式 |
|---|---|
指定合成語音的目標語言 | 使用 |
修正特定詞語的發音或取代文字 | 使用 |
精細控制停頓、數字讀法或字詞發音 | 使用 SSML 標籤標記需要控制的文字,按標籤設定停頓、讀法和發音等效果。 |
朗讀數學公式 | 使用 CosyVoice 的 LaTeX 公式朗讀功能,將支援的數學公式轉換為中文語音。 |
參數適用模型和設定方法請參見 Qwen-Audio-TTS API或 CosyVoice API;SSML 與 LaTeX 的適用模型、音色、介面及用法請參見 SSML 與 LaTeX。
說明使用 SSML 時,需要一次提交完整的 SSML 文字,再逐段接收音訊,不支援分段輸入。
指令控制
透過 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 中說明合成語種和所需效果,以提升合成品質。指令中指定的語種須與待合成文字的語種一致。例如,合成荷蘭語文字時,可設定:
请用荷兰话说,每个字都慢慢说
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指定方言。
對於支援方言指令的音色,在初始化 SpeechSynthesizer 時傳入 instruction="请讲上海话。",可將中文文字合成為上海話。
CosyVoice
- 系統音色:選擇直接支援目標方言的音色,例如
longshange_v3;或選擇支援方言指令的音色,例如longanhuan_v3,依音色清單的格式填寫指令。 - 複製音色:使用支援指令控制的模型,透過
instruction指定方言。 - 設計音色:暫不支援方言。
使用 CosyVoice 的 Python 開始使用範例時,將初始化與文字傳送部分替換為以下內容,可使用 longanhuan_v3 輸出河南話:
with client.audio.tts.connect(
model="cosyvoice-v3-flash",
voice="longanhuan_v3",
parameters={"instruction": "请用河南话表达。"}, # 指令控制
format="mp3",
sample_rate=24000,
) as session:
session.send_text("叫你去买盐,你买回来一袋面,这不是弄啥嘞吗!")
session.flush()
使用 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 或 CosyVoice 模型時,如需中斷目前輪次合成,可傳送取消指令。服務端會結束目前任務並傳回 task-finished。
| 呼叫方式 | 版本要求 | 使用方法 |
|---|---|---|
Python SDK | 2.0.1 及以上版本 | 呼叫會話物件的 |
Java SDK | 2.22.26 及以上版本 | 呼叫 |
WebSocket 原始協議 | 無需 SDK | 傳送 |
支援模型
新加坡
- 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-plus、cosyvoice-v3-flash
- Qwen3-TTS:qwen3-tts-flash-realtime
華北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-realtime
系統音色與試聽分別參見 Qwen-Audio-TTS、CosyVoice和 Qwen3-TTS 音色清單。使用複製或設計音色時,合成模型須與建立音色時指定的目標模型一致。
API 參考
對延遲和弱網路下音訊傳輸穩定性要求較高的行動應用程式,可使用 AOQ 通訊協定。AOQ 的接入方式,以及 AOQ、WebRTC 和 WebSocket 的差異與模型支援範圍,請參見 Realtime API 概述。
常見問題
使用複刻音色產生的音頻無聲音如何排查?
確認 voice 為建立成功的音色 ID,建立音色時的 target_model 與合成時的 model 一致。音色狀態、來源音訊要求及品質建議請參見音色複刻。
如何限制 API Key 僅用於語音合成服務(許可權隔離)?
通過建立業務空間並僅授權特定模型,可限制 API Key 的使用範圍。請參見業務空間管理。