前提條件
Qwen-Audio-TTS
介面地址
SDK的介面地址由Client構造參數workspace/region決定(對應下方地址,包含WorkspaceId)。如需切換到其他地區,請修改Client構造參數為對應地區的值。
新加坡
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference
調用時請將{WorkspaceId}替換為真實的Workspace ID。
華北2(北京)
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference
調用時請將{WorkspaceId}替換為真實的Workspace ID。
重要阿里雲百鍊為華北2(北京)、新加坡地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:
- 華北2(北京)地區:從
dashscope.aliyuncs.com遷移至{WorkspaceId}.cn-beijing.maas.aliyuncs.com - 新加坡地區:從
dashscope-intl.aliyuncs.com遷移至{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
CosyVoice
介面地址
SDK的介面地址由Client構造參數workspace/region決定(對應下方地址,包含WorkspaceId)。如需切換到其他地區,請修改Client構造參數為對應地區的值。
新加坡
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference
調用時請將{WorkspaceId}替換為真實的Workspace ID。
華北2(北京)
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference
調用時請將{WorkspaceId}替換為真實的Workspace ID。
dashscope CLI
通過 dashscope 命令列調用。
export DASHSCOPE_API_KEY="your-api-key"
# 將 {WorkspaceId} 替換為北京地區的業務空間ID。
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"
dashscope speech-synthesis create -m cosyvoice-v3-plus -t "你好世界" --voice longanyang
重要SDK Expert 互動式助手可按自然語言完成同樣的開發與排障,見
DashScope SDK Expert。完整地區表見 Base URL 總覽。
重要阿里雲百鍊為華北2(北京)、新加坡地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:
- 華北2(北京)地區:從
dashscope.aliyuncs.com遷移至{WorkspaceId}.cn-beijing.maas.aliyuncs.com - 新加坡地區:從
dashscope-intl.aliyuncs.com遷移至{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
快速開始
Qwen-Audio-TTS
SDK提供了語音合成的關鍵介面,支援以下幾種調用方式:
- 非流式調用:阻塞式,一次性發送完整文本,直接返回完整音頻。適合短文本語音合成情境。
- 單向流式調用:非阻塞式,一次性發送完整文本,通過迭代
stream傳回的音頻分區接收資料。適用於對即時性要求高的短文本語音合成情境。 - 雙向流式調用:非阻塞式,可分多次發送文本片段,通過會話的
audio_chunks()/events()迭代即時接收增量合成的音頻流。適合即時性要求高的長文本語音合成情境。
非流式調用
單次調用發送的文本長度不得超過20000字元,超出限制將返回錯誤。
重要synthesize與stream每次調用自建會話,無需複用執行個體。
# coding=utf-8
import os
import dashscope
# 新加坡地區和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key = "sk-xxx"
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# 模型
model = "qwen-audio-3.0-tts-flash"
# 音色
voice = "longanhuan_v3.6"
# 發送待合成文本,擷取二進位音頻
audio = client.audio.tts.synthesize("今天天氣怎麼樣?", model=model, voice=voice)
# 將音頻儲存至本地
with open('output.mp3', 'wb') as f:
f.write(audio)
單向流式調用
單次調用發送的文本長度不得超過20000字元,超出限制將返回錯誤。
重要synthesize與stream每次調用自建會話,無需複用執行個體。
# coding=utf-8
import os
from datetime import datetime
import dashscope
def get_timestamp():
now = datetime.now()
formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
return formatted_timestamp
# 新加坡地區和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key = "sk-xxx"
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# 模型
model = "qwen-audio-3.0-tts-flash"
# 音色
voice = "longanhuan_v3.6"
# 一次性發送完整文本,逐塊接收二進位音頻
with open("output.mp3", "wb") as f:
for chunk in client.audio.tts.stream("今天天氣怎麼樣?", model=model, voice=voice):
print(get_timestamp() + " 二進位音頻長度為:" + str(len(chunk)))
f.write(chunk)
print("語音合成完成,所有合成結果已被接收:" + get_timestamp())
雙向流式調用
單次發送文本長度不得超過 20000 字元,且累計發送文本總長度不得超過 20 萬字元。
-
流式輸入時可多次調用會話的
send_text按順序提交文本片段。服務端接收文本片段後自動進行分句:- 完整語句立即合成
- 不完整語句緩衝至完整後合成
調用
stop時,服務端會強制合成所有已接收但未處理的文本片段(包括未完成的句子)。 -
發送文本片段的間隔不得超過23秒,否則觸發“request timeout after 23 seconds”異常。
若無待發送文本,需及時調用
stop結束任務。重要請務必確保調用
stop方法,否則可能會導致結尾部分的文本無法成功轉換為語音。服務端強制設定23秒逾時機制,用戶端無法修改該配置。
# coding=utf-8
#
# pyaudio安裝說明:
# 如果是macOS作業系統,執行如下命令:
# brew install portaudio
# pip install pyaudio
# 如果是Debian/Ubuntu作業系統,執行如下命令:
# sudo apt-get install python-pyaudio python3-pyaudio
# 或者
# pip install pyaudio
# 如果是CentOS作業系統,執行如下命令:
# sudo yum install -y portaudio portaudio-devel && pip install pyaudio
# 如果是Microsoft Windows,執行如下命令:
# python -m pip install pyaudio
import os
import time
import pyaudio
from concurrent.futures import ThreadPoolExecutor
import dashscope
from datetime import datetime
def get_timestamp():
now = datetime.now()
formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
return formatted_timestamp
# 新加坡地區和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key = "sk-xxx"
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# 模型
model = "qwen-audio-3.0-tts-flash"
# 音色
voice = "longanhuan_v3.6"
test_text = [
"流式文本語音合成SDK,",
"可以將輸入的文本",
"合成為語音位元據,",
"相比於非流式語音合成,",
"流式合成的優勢在於即時性",
"更強。使用者在輸入文本的同時",
"可以聽到接近同步的語音輸出,",
"極大地提升了互動體驗,",
"減少了使用者等待時間。",
"適用於調用大規模",
"語言模型(LLM),以",
"流式輸入文本的方式",
"進行語音合成的情境。",
]
# 建立雙向流式合成會話:進入with上下文時自動建立串連
with client.audio.tts.connect(
model=model,
voice=voice,
format="pcm",
sample_rate=22050,
) as session:
# 初始化播放器
player = pyaudio.PyAudio()
stream = player.open(format=pyaudio.paInt16, channels=1, rate=22050, output=True)
# 接收線程:迭代音頻資料並即時播放
def receive_audio():
for chunk in session.audio_chunks():
print(get_timestamp() + " 二進位音頻長度為:" + str(len(chunk)))
stream.write(chunk)
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_audio)
# 流式發送待合成文本
for text in test_text:
session.send_text(text)
time.sleep(0.1)
# 結束流式合成
session.stop()
receiver.result()
print("語音合成完成,所有合成結果已被接收:" + get_timestamp())
# 停止播放器
stream.stop_stream()
stream.close()
player.terminate()
# 首次發送文本時需建立 WebSocket 串連,因此首包延遲會包含串連建立的耗時
print('[Metric] 首包延遲為:{}毫秒'.format(session.first_package_delay))
CosyVoice
SDK提供了語音合成的關鍵介面,支援以下幾種調用方式:
- 非流式調用:阻塞式,一次性發送完整文本,直接返回完整音頻。適合短文本語音合成情境。
- 單向流式調用:非阻塞式,一次性發送完整文本,通過迭代
stream返回的音頻分區接收資料。適用於對即時性要求高的短文本語音合成情境。 - 雙向流式調用:非阻塞式,可分多次發送文本片段,通過會話的
audio_chunks()/events()迭代即時接收增量合成的音頻流。適合即時性要求高的長文本語音合成情境。
非流式調用
單次調用發送的文本長度不得超過20000字元,超出限制將觸發 DashScopeError 異常。
重要synthesize與stream每次調用自建會話,無需複用執行個體。
# coding=utf-8
import os
import dashscope
# 新加坡地區和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用阿里雲百鍊API Key將下行替換為:api_key = "sk-xxx"
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# 模型
model = "cosyvoice-v3-plus"
# 音色
voice = "longanyang"
# 發送待合成文本,擷取二進位音頻
audio = client.audio.tts.synthesize("今天天氣怎麼樣?", model=model, voice=voice)
# 將音頻儲存至本地
with open('output.mp3', 'wb') as f:
f.write(audio)
單向流式調用
單次調用發送的文本長度不得超過20000字元,超出限制將觸發 DashScopeError 異常。
重要synthesize與stream每次調用自建會話,無需複用執行個體。
# coding=utf-8
import os
from datetime import datetime
import dashscope
def get_timestamp():
now = datetime.now()
formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
return formatted_timestamp
# 新加坡地區和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用阿里雲百鍊API Key將下行替換為:api_key = "sk-xxx"
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# 模型
model = "cosyvoice-v3-plus"
# 音色
voice = "longanyang"
# 一次性發送完整文本,逐塊接收二進位音頻
with open("output.mp3", "wb") as f:
for chunk in client.audio.tts.stream("今天天氣怎麼樣?", model=model, voice=voice):
print(get_timestamp() + " 二進位音頻長度為:" + str(len(chunk)))
f.write(chunk)
print("語音合成完成,所有合成結果已被接收:" + get_timestamp())
雙向流式調用
單次發送文本長度不得超過 20000 字元,且累計發送文本總長度不得超過 20 萬字元。
-
流式輸入時可多次調用會話的
send_text按順序提交文本片段。服務端接收文本片段後自動進行分句:- 完整語句立即合成
- 不完整語句緩衝至完整後合成
調用
stop時,服務端會強制合成所有已接收但未處理的文本片段(包括未完成的句子)。 -
發送文本片段的間隔不得超過23秒,否則觸發“request timeout after 23 seconds”異常。
若無待發送文本,需及時調用
stop結束任務。重要請務必確保調用
stop方法,否則可能會導致結尾部分的文本無法成功轉換為語音。服務端強制設定23秒逾時機制,用戶端無法修改該配置。
# coding=utf-8
#
# pyaudio安裝說明:
# 如果是macOS作業系統,執行如下命令:
# brew install portaudio
# pip install pyaudio
# 如果是Debian/Ubuntu作業系統,執行如下命令:
# sudo apt-get install python-pyaudio python3-pyaudio
# 或者
# pip install pyaudio
# 如果是CentOS作業系統,執行如下命令:
# sudo yum install -y portaudio portaudio-devel && pip install pyaudio
# 如果是Microsoft Windows,執行如下命令:
# python -m pip install pyaudio
import os
import time
import pyaudio
from concurrent.futures import ThreadPoolExecutor
import dashscope
from datetime import datetime
def get_timestamp():
now = datetime.now()
formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
return formatted_timestamp
# 新加坡地區和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用阿里雲百鍊API Key將下行替換為:api_key = "sk-xxx"
# 以下為新加坡地區的配置,調用時請將{WorkspaceId}替換為真實的業務空間ID,各地區的region取值不同。
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# 模型
model = "cosyvoice-v3-plus"
# 音色
voice = "longanyang"
test_text = [
"流式文本語音合成SDK,",
"可以將輸入的文本",
"合成為語音位元據,",
"相比於非流式語音合成,",
"流式合成的優勢在於即時性",
"更強。使用者在輸入文本的同時",
"可以聽到接近同步的語音輸出,",
"極大地提升了互動體驗,",
"減少了使用者等待時間。",
"適用於調用大規模",
"語言模型(LLM),以",
"流式輸入文本的方式",
"進行語音合成的情境。",
]
# 建立雙向流式會話:進入with上下文時自動建立串連
with client.audio.tts.connect(
model=model,
voice=voice,
format="pcm",
sample_rate=22050,
) as session:
# 初始化播放器
player = pyaudio.PyAudio()
stream = player.open(format=pyaudio.paInt16, channels=1, rate=22050, output=True)
# 接收線程:迭代音頻資料並即時播放
def receive_audio():
for chunk in session.audio_chunks():
print(get_timestamp() + " 二進位音頻長度為:" + str(len(chunk)))
stream.write(chunk)
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_audio)
# 流式發送待合成文本
for text in test_text:
session.send_text(text)
time.sleep(0.1)
# 結束流式合成
session.stop()
receiver.result()
print("語音合成完成,所有合成結果已被接收:" + get_timestamp())
# 停止播放器
stream.stop_stream()
stream.close()
player.terminate()
# 首次發送文本時需建立 WebSocket 串連,因此首包延遲會包含串連建立的耗時
print('[Metric] 首包延遲為:{}毫秒'.format(session.first_package_delay))
請求參數
Qwen-Audio-TTS
以下參數通過client.audio.tts的synthesize/stream/connect方法設定,用於控制合成音頻的模型、音色、格式和音頻特徵(model、voice、format、sample_rate、volume、rate、pitch、language_hints、enable_ssml為具名參數,其餘參數通過parameters字典傳入)。
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
model | str | 是 | 模型名稱。 |
voice | str | 是 | 語音合成所使用的音色。
|
format | str | 否 | 音頻編碼格式。 預設值:mp3。 支援mp3、wav、pcm等格式;採樣率通過 |
volume | int | 否 | 音量。 預設值:50。 取值範圍:[0, 100]。 |
rate | float | 否 | 語速。 預設值:1.0。 取值範圍:[0.5, 2.0]。 |
pitch | float | 否 | 音調。 預設值:1.0。 取值範圍:[0.5, 2.0]。 |
bit_rate | int | 否 | 音頻碼率(kbps)。音頻格式為mp3或opus時,支援通過bit_rate參數調整碼率。預設值:32。 取值範圍:[6, 510]。
|
word_timestamp_enabled | bool | 否 | 是否開啟字層級時間戳記。 預設值:false。 僅在流式輸出模式下可用。支援複製音色;支援的系統音色請參見Qwen-Audio-TTS音色列表。
|
seed | int | 否 | 產生時使用的隨機數種子,使合成的效果產生變化。在模型版本、文本、音色及其他參數均相同的前提下,使用相同的seed可複現相同的合成結果。 預設值0。 取值範圍:[0, 65535]。 |
language_hints | list[str] | 否 | 說明使用 qwen-audio-3.1-tts-flash 的多語種與方言音色時,可透過此參數指定語種或方言。具體用法請參見多語種與方言音色的設定方法。 指定語音合成的目標語言,提升合成效果。 當數字、縮寫、符號等朗讀方式或者小語種合成效果不符合預期時使用,例如:
取值範圍
說明
|
instruction | str | 否 | 設定指令,用於控制方言、情感或角色等合成效果。 使用說明請參見指令控制。 |
enable_aigc_tag | bool | 否 | 是否在產生的音頻中添加AIGC隱性標識。設定為true時,會將隱性標識嵌入到支援格式(wav/mp3/opus)的音頻中。 預設值:false。
|
aigc_propagator | str | 否 | 設定AIGC隱性標識中的 ContentPropagator 欄位,用於標識內容的傳播者。僅在 enable_aigc_tag 為 true 時生效。預設值:阿里雲UID。 需要通過 |
aigc_propagate_id | str | 否 | 設定AIGC隱性標識中的 PropagateID 欄位,用於唯一標識一次具體的傳播行為。僅在 enable_aigc_tag 為 true 時生效。預設值:本次語音合成請求Request ID。 需要通過 |
hot_fix | dict | 否 | 文本熱修複配置,用於自訂指定詞語的發音或對待合成文本進行替換。 參數介紹:
樣本: |
|
| 否 | 是否啟用 Markdown 過濾。啟用後,服務會在合成前將 Markdown 轉換為適合朗讀的文字。 預設值: 透過 |
CosyVoice
以下參數通過client.audio.tts的synthesize/stream/connect方法設定,用於控制合成音頻的模型、音色、格式和音頻特徵(model、voice、format、sample_rate、volume、rate、pitch、language_hints、enable_ssml為具名參數,其餘參數通過parameters字典傳入)。
| 參數 | 類型 | 是否必須 | 說明 |
|---|---|---|---|
model | str | 是 | 模型名稱。 |
voice | str | 是 | 語音合成所使用的音色。
|
format | str | 否 | 音頻編碼格式。 預設值:mp3。 支援mp3、wav、pcm等格式;採樣率通過 |
volume | int | 否 | 音量。 預設值:50。 取值範圍:[0, 100]。 |
rate | float | 否 | 語速。 預設值:1.0。 取值範圍:[0.5, 2.0]。 |
pitch | float | 否 | 音調。 預設值:1.0。 取值範圍:[0.5, 2.0]。 |
bit_rate | int | 否 | 音頻碼率(kbps)。音頻格式為mp3或opus時,支援通過bit_rate參數調整碼率。預設值:32。 取值範圍:[6, 510]。
|
word_timestamp_enabled | bool | 否 | 是否開啟字層級時間戳記。 預設值:false。 僅在流式輸出模式下可用。支援的音色範圍:cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2模型的複刻音色,以及CosyVoice音色列表中標記為支援的系統音色。其他模型的複刻音色不支援此功能。
|
seed | int | 否 | 產生時使用的隨機數種子,使合成的效果產生變化。在模型版本、文本、音色及其他參數均相同的前提下,使用相同的seed可複現相同的合成結果。 預設值0。 取值範圍:[0, 65535]。 |
language_hints | list[str] | 否 | 重要
指定語音合成的目標語言,提升合成效果。 當數字、縮寫、符號等朗讀方式或者小語種合成效果不符合預期時使用,例如:
取值範圍
|
instruction | str | 否 | 設定指令,用於控制方言、情感或角色等合成效果。 使用說明請參見指令控制。 |
enable_aigc_tag | bool | 否 | 是否在產生的音頻中添加AIGC隱性標識。設定為true時,會將隱性標識嵌入到支援格式(wav/mp3/opus)的音頻中。 預設值:false。 說明僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。
|
aigc_propagator | str | 否 | 設定AIGC隱性標識中的 ContentPropagator 欄位,用於標識內容的傳播者。僅在 enable_aigc_tag 為 true 時生效。預設值:阿里雲UID。 說明僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。 需要通過 |
aigc_propagate_id | str | 否 | 設定AIGC隱性標識中的 PropagateID 欄位,用於唯一標識一次具體的傳播行為。僅在 enable_aigc_tag 為 true 時生效。預設值:本次語音合成請求Request ID。 說明僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。 需要通過 |
hot_fix | dict | 否 | 文本熱修複配置,用於自訂指定詞語的發音或對待合成文本進行替換。 說明cosyvoice-v2不支援該功能。 參數介紹:
樣本: |
enable_markdown_filter | bool | 否 | 說明cosyvoice-v2 不支援此功能。 是否啟用 Markdown 過濾。啟用後,服務會在合成前將 Markdown 轉換為適合朗讀的文字。 預設值:false。 取值範圍:
|
介面參考
核心資源(client.audio.tts)
資源路徑:client.audio.tts
功能:基於WebSocket的語音合成,提供一次性合成(synthesize)、流式合成(stream)與雙向流式會話(connect)三種調用形態。
stream() - 流式調用
方法簽名:
def stream(self, text: str, *, model: str, voice: str,
format: str = "mp3", sample_rate: int = 22050, ...) -> Iterator[bytes]
參數說明:
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
text | str | 是 | 待合成的完整文本,長度不得超過20000字元。 |
傳回值:Iterator[bytes],逐塊產出的音頻資料。
說明:流式合成,一次性發送完整文本並逐塊產出音頻(Iterator[bytes])。適用於對即時性要求高的短文本語音合成情境。需要分區提交文本時請使用雙向流式會話(connect)。
send_text() - 流式輸入(會話方法)
雙向流式會話(client.audio.tts.connect(...))中分區提交文本。
方法簽名:
def send_text(self, text: str) -> None
參數說明:text為當前待合成的文本片段。可多次調用send_text以追加文本,單次不超過20000字元,累計不超過20萬字元。發送文本與接收音頻需並發進行(配合audio_chunks()/events()和stop使用)。
stop() - 結束流式輸入(會話方法)
方法簽名:
def stop(self) -> None
說明:通知服務端所有文本已發送完畢。調用後不阻塞當前線程,接收線程需繼續消費audio_chunks()/events()直到剩餘文本合成完成並返回所有音頻資料。未調用此方法可能導致尾部文本無法轉換為語音。
會話指標與響應(會話屬性)
session.first_package_delay
session.usage
session.last_response
first_package_delay:float,從發送文本到收到第一塊音頻資料的延遲時間(毫秒)。需在合成完成後讀取。usage:dict,最近一次合成任務的用量資訊。last_response:dict,最近一次合成任務的響應訊息(含header/payload鍵)。最近一次請求的request_id可從session.last_response的header中擷取,可用於問題排查和日誌關聯。
events() - 迭代服務端事件
方法簽名:
def events(self) -> Generator[Union[Dict, bytes], None, None]
傳回值:同時產出服務端響應事件(dict,包含header(請求資訊)和payload(輸出資訊))與音頻bytes。其中payload.output包含事件類型、原始文本等資訊,詳見events()事件中的output欄位。
說明:在接收線程中迭代服務端回複,包含合成事件的輸出資訊(事件類型、原始文本、句子資訊等),可直接訪問payload.output擷取詳細資料。
會話生命週期
- 進入
with上下文時自動建立串連(可在此前初始化音頻輸出流或開啟檔案等資源)。 - 所有文本合成完成且音頻資料已全部產出後,
events()/audio_chunks()迭代結束;此後可讀取first_package_delay等效能指標。 - 退出
with上下文時自動關閉串連(可在此後釋放音頻播放裝置等資源)。
events()事件中的output欄位
會話events()迭代產出的事件dict中,payload.output包含合成事件的輸出資訊,可用於跟蹤合成進度和擷取逐句資訊。以下為output欄位的結構說明:
| 欄位 | 類型 | 說明 |
|---|---|---|
type | str | 事件類型。取值為sentence-begin(句子合成開始)、sentence-synthesis(句子合成中)或sentence-end(句子合成結束)。 |
original_text | str | 當前句子的原始文本。在sentence-begin和sentence-end事件中返回。 |
sentence | dict | 句子資訊。包含index(句子序號)和words(詞列表,開啟word_timestamp_enabled時返回時間戳記資訊)。 |
訊息樣本:
{
"header": {
"task_id": "xxx",
"event": "result-generated",
"attributes": {}
},
"payload": {
"output": {
"type": "sentence-begin",
"original_text": "今天天氣怎麼樣?",
"sentence": {
"index": 0,
"words": []
}
}
}
}
解析樣本:
def handle_event(event):
output = (event.get('payload') or {}).get('output') or {}
event_type = output.get('type', '')
original_text = output.get('original_text', '')
if event_type:
print(f'事件類型: {event_type}, 原始文本: {original_text}')
Qwen-Audio-TTS
共用說明
- 核心資源(
client.audio.tts) - stream() - 流式調用
- send_text() - 流式輸入(會話方法)
- stop() - 結束流式輸入(會話方法)
- 會話指標與響應(會話屬性)
- events() - 迭代服務端事件
- 會話生命週期
- events()事件中的output欄位
請參閱新版 Qwen-Audio-TTS Python SDK。
調用入口
# 一次性合成:返回完整的音頻二進位資料
audio = client.audio.tts.synthesize(
text, # text 為必填(位置參數)
model="qwen-audio-3.0-tts-flash", # 音色所屬的模型
voice="longanhuan_v3.6", # 音色
format="mp3", # 音頻編碼格式,預設 "mp3"
sample_rate=22050, # 採樣率,預設 22050
)
# 流式合成:逐塊產出音頻二進位資料(可邊接收邊寫入/播放)
for chunk in client.audio.tts.stream(text, model=..., voice=...):
...
# 雙向流式會話:分段發送文本;進入with上下文時自動建立串連
with client.audio.tts.connect(model=..., voice=...) as session:
session.send_text(text) # 可多次調用以追加文本
session.stop() # 通知服務端輸入已完成
for chunk in session.audio_chunks():
...
synthesize() - 非流式調用
方法簽名:
def synthesize(self, text: str, *, model: str,
voice: str, format: str = "mp3",
sample_rate: int = 22050, volume: int = None,
rate: float = None, pitch: float = None,
language_hints: list = None, enable_ssml: bool = None,
parameters: Dict = None, ...) -> bytes
參數說明:
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
text | str | 是 | 待合成的完整文本,長度不得超過20000字元。 |
傳回值:bytes,完整音頻資料。
說明:非流式調用,阻塞等待並一次性返回完整音頻資料。適用於短文本、對即時性無嚴格要求的情境。synthesize與stream每次調用自建會話,無需複用執行個體。
cancel() - 取消流式合成(會話方法)
方法簽名:
def cancel(self) -> None
說明:取消當前輪次的流式語音合成任務。調用後,SDK 會立即結束當前任務。取消後當前會話不能再發送文本,如需繼續合成請新建會話。
會話與事件迭代
流式合成不再使用回調介面:音頻與服務端事件通過會話的迭代方法接收。stream()/synthesize()無需會話管理;雙向流式會話(client.audio.tts.connect(...))的生命週期為:進入with上下文自動建立串連 → 多次send_text() → stop() → 讀完全部結果 → 退出上下文自動關閉。
audio_chunks() - 迭代音頻資料
方法簽名:
def audio_chunks(self) -> Iterator[bytes]
傳回值:Iterator[bytes],逐塊產出的音頻二進位資料片段,格式由format參數指定。
說明:在接收線程中迭代,逐塊接收音頻資料,合成過程中會產出多塊。可將資料寫入檔案或送入播放裝置。同一會話只允許一個events()或audio_chunks()讀取者。
錯誤處理
合成過程中發生錯誤時,ws層會以DashScopeError異常拋出,異常觸發後串連將自動關閉。可在發送/接收處使用try/except捕獲並記錄錯誤日誌以便排查問題:
from dashscope import DashScopeError
try:
...
except DashScopeError as e:
print(e.code, e.message, e.request_id)
CosyVoice
共用說明
- 核心資源(
client.audio.tts) - stream() - 流式調用
- send_text() - 流式輸入(會話方法)
- stop() - 結束流式輸入(會話方法)
- 會話指標與響應(會話屬性)
- events() - 迭代服務端事件
- 會話生命週期
- events()事件中的output欄位
請參閱新版 CosyVoice Python SDK。
調用入口
# 一次性合成:返回完整音頻位元組
audio = client.audio.tts.synthesize(
text, # text為必填參數(位置參數)
model="cosyvoice-v3-plus", # 音色所屬的模型
voice="longanyang", # 音色
format="mp3", # 音頻編碼格式,預設"mp3"
sample_rate=22050, # 採樣率,預設22050
)
# 流式合成:逐塊產出音頻位元組(可邊接收邊寫入/播放)
for chunk in client.audio.tts.stream(text, model=..., voice=...):
...
# 雙向流式會話:分段發送文本;進入with上下文時自動建立串連
with client.audio.tts.connect(model=..., voice=...) as session:
session.send_text(text) # 可多次調用以追加文本
session.stop() # 通知服務端輸入已完成
for chunk in session.audio_chunks():
...
synthesize() - 非流式調用
方法簽名:
def synthesize(self, text: str, *, model: str = "cosyvoice-v1",
voice: str = "longxiaochun", format: str = "mp3",
sample_rate: int = 22050, volume: int = None,
rate: float = None, pitch: float = None,
language_hints: list = None, enable_ssml: bool = None,
parameters: Dict = None, ...) -> bytes
參數說明:
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
text | str | 是 | 待合成的完整文本,長度不得超過20000字元。 |
傳回值:bytes,完整音頻資料。
說明:非流式調用,阻塞等待並一次性返回完整音頻資料。適用於短文本、對即時性無嚴格要求的情境。synthesize與stream每次調用自建會話,無需複用執行個體。
cancel() - 取消流式合成(會話方法)
方法簽名:
def cancel(self) -> None
說明:取消當前輪次的流式語音合成任務。調用後,SDK 會立即結束當前任務。取消後當前會話不能再發送文本,如需繼續合成請新建會話。
重要模型限制:
- 華北2(北京)地區:CosyVoice 系列模型僅 v2 及以上版本支援該功能。
- 新加坡地區:CosyVoice 系列模型不支援該功能。
會話與事件迭代
流式合成不再使用回調介面:音頻與服務端事件通過會話的迭代方法接收。stream()/synthesize()無需會話管理;雙向流式會話(client.audio.tts.connect(...))的生命週期為:進入with上下文自動建立串連 → 多次send_text() → stop() → 讀完全部結果 → 退出上下文自動關閉。
audio_chunks() - 迭代音頻資料
方法簽名:
def audio_chunks(self) -> Iterator[bytes]
傳回值:Iterator[bytes],逐塊產出的音頻位元據片段,格式由format參數指定。
說明:在接收線程中迭代,逐塊接收音頻資料,合成過程中會產出多塊。可將資料寫入檔案或送入播放裝置。同一會話只允許一個events()或audio_chunks()讀取者。
錯誤處理
合成過程中發生錯誤時,ws層會以DashScopeError異常拋出,異常觸發後串連將自動關閉。可在發送/接收處使用try/except捕獲並記錄錯誤記錄檔以便排查問題:
from dashscope import DashScopeError
try:
...
except DashScopeError as e:
print(e.code, e.message, e.request_id)