全部產品
Search
文件中心

Alibaba Cloud Model Studio:Qwen-Audio-TTS / CosyVoice Python SDK

更新時間:Nov 19, 2026

前提條件

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字典傳入)。

參數類型是否必須說明
modelstr是模型名稱。
voicestr是語音合成所使用的音色。
  • 系統音色:參見Qwen-Audio-TTS音色列表
  • 複刻音色:通過聲音複刻功能定製
  • 聲音設計音色:通過聲音設計功能定製
formatstr否音頻編碼格式。

預設值:mp3。

支援mp3、wav、pcm等格式;採樣率通過sample_rate參數設定,預設22050。

volumeint否音量。

預設值:50。

取值範圍:[0, 100]。

ratefloat否語速。

預設值:1.0。

取值範圍:[0.5, 2.0]。

pitchfloat否音調。

預設值:1.0。

取值範圍:[0.5, 2.0]。

bit_rateint否音頻碼率(kbps)。音頻格式為mp3或opus時,支援通過bit_rate參數調整碼率。

預設值:32。

取值範圍:[6, 510]。

bit_rate需要通過parameters字典進行設定:

audio = client.audio.tts.synthesize(
    "待合成文本",
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6",
    parameters={"bit_rate": 128},
)
word_timestamp_enabledbool否是否開啟字層級時間戳記。

預設值:false。

僅在流式輸出模式下可用。支援複製音色;支援的系統音色請參見Qwen-Audio-TTS音色列表。

word_timestamp_enabled需要通過parameters字典進行設定:

audio = client.audio.tts.stream(
    "待合成文本",
    model="qwen-audio-3.0-tts-flash",
    voice="your_voice",  # 支援字層級時間戳記的系統音色或複刻音色
    parameters={"word_timestamp_enabled": True},
)
seedint否產生時使用的隨機數種子,使合成的效果產生變化。在模型版本、文本、音色及其他參數均相同的前提下,使用相同的seed可複現相同的合成結果。

預設值0。

取值範圍:[0, 65535]。

language_hintslist[str]否

說明使用 qwen-audio-3.1-tts-flash 的多語種與方言音色時,可透過此參數指定語種或方言。具體用法請參見多語種與方言音色的設定方法。

指定語音合成的目標語言,提升合成效果。

當數字、縮寫、符號等朗讀方式或者小語種合成效果不符合預期時使用,例如:

  • 數字朗讀方式不符合預期,“hello, this is 110”讀成“hello, this is one one zero”而非“hello, this is 么么零”
  • 符號朗讀不準確,“@”讀成“艾特”而非“at”
  • 小語種合成效果差,合成不自然

取值範圍

  • zh:中文

  • en:英語

  • fr:法語

  • de:德語

  • ja:日語

  • ko:韓語

  • ru:俄語

  • pt:葡萄牙語

  • th:泰語

  • id:印尼語

  • vi:越南語

  • es:西班牙語

  • it:意大利語

  • ms:馬來語

  • fil:菲律賓語

  • ar:阿拉伯語

  • other:其他語種(適用於 qwen-audio-3.1-tts-flash)

    保加利亞語、荷蘭語、匈牙利語、羅馬尼亞語、丹麥語、克羅埃西亞語、希臘語、捷克語、挪威語、瑞典語、印地語、斯洛伐克語、芬蘭語、烏都語、塞爾維亞語、西班牙語(墨西哥)、立陶宛語、拉脫維亞語、土耳其語、波斯語、希伯來語、蒙古語、斯洛維尼亞語、亞塞拜然語、波蘭語、加泰蘭語、高棉語、葡萄牙語(巴西)、寮語、喬治亞語、南非荷蘭語、尼泊爾語、白俄羅斯語、馬來亞拉姆語、盧森堡語、阿爾巴尼亞語、坦米爾語、僧伽羅語、泰盧固語、愛沙尼亞語、宿霧語、波士尼亞語、緬甸語、亞美尼亞語、拉丁語、冰島語、馬爾他語、史瓦希里語、哈薩克語、塞席爾克里奧爾法語、烏克蘭語。

說明

  • 此參數為數組,但目前的版本僅處理第一個元素,因此建議只傳入一個值。
  • 此參數用於指定語音合成的目標語言,該設定與聲音複刻時的樣本音訊語種無關。如需設定複刻任務的源語言,請參見聲音複刻API參考。
instructionstr否設定指令,用於控制方言、情感或角色等合成效果。

使用說明請參見指令控制。

enable_aigc_tagbool否是否在產生的音頻中添加AIGC隱性標識。設定為true時,會將隱性標識嵌入到支援格式(wav/mp3/opus)的音頻中。

預設值:false。

enable_aigc_tag、aigc_propagator和aigc_propagate_id需要通過parameters字典進行設定:

audio = client.audio.tts.synthesize(
    "待合成文本",
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6",
    parameters={
        "enable_aigc_tag": True,
        "aigc_propagator": "your_propagator",
        "aigc_propagate_id": "your_propagate_id"
    },
)
aigc_propagatorstr否設定AIGC隱性標識中的 ContentPropagator 欄位,用於標識內容的傳播者。僅在 enable_aigc_tag 為 true 時生效。

預設值:阿里雲UID。

需要通過parameters字典進行設定,參見enable_aigc_tag的樣本。

aigc_propagate_idstr否設定AIGC隱性標識中的 PropagateID 欄位,用於唯一標識一次具體的傳播行為。僅在 enable_aigc_tag 為 true 時生效。

預設值:本次語音合成請求Request ID。

需要通過parameters字典進行設定,參見enable_aigc_tag的樣本。

hot_fixdict否文本熱修複配置,用於自訂指定詞語的發音或對待合成文本進行替換。

參數介紹:

  • pronunciation:自訂發音。指定詞語的拼音標註,用於糾正預設發音不準確的情況。
  • replace:文本替換。在語音合成前將指定詞語替換為目標文本,替換後的文本將作為實際合成內容。

樣本:

audio = client.audio.tts.synthesize(
    "今天的天气很好。",
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6", # 音色
    parameters={
        "hot_fix": {
            "pronunciation": [{"天气": "tian1 qi4"}],
            "replace": [{"今天": "明天"}]
        }
    },
)

enable_markdown_filter

bool

否

是否啟用 Markdown 過濾。啟用後,服務會在合成前將 Markdown 轉換為適合朗讀的文字。

預設值:False。設為 True 即可啟用。

透過 parameters={"enable_markdown_filter": True} 啟用。

CosyVoice

以下參數通過client.audio.tts的synthesize/stream/connect方法設定,用於控制合成音頻的模型、音色、格式和音頻特徵(model、voice、format、sample_rate、volume、rate、pitch、language_hints、enable_ssml為具名參數,其餘參數通過parameters字典傳入)。

參數類型是否必須說明
modelstr是模型名稱。
voicestr是語音合成所使用的音色。
  • 系統音色:參見CosyVoice音色列表
  • 複刻音色:通過聲音複刻功能定製
  • 聲音設計音色:通過聲音設計功能定製
formatstr否音頻編碼格式。

預設值:mp3。

支援mp3、wav、pcm等格式;採樣率通過sample_rate參數設定,預設22050。

volumeint否音量。

預設值:50。

取值範圍:[0, 100]。

ratefloat否語速。

預設值:1.0。

取值範圍:[0.5, 2.0]。

pitchfloat否音調。

預設值:1.0。

取值範圍:[0.5, 2.0]。

bit_rateint否音頻碼率(kbps)。音頻格式為mp3或opus時,支援通過bit_rate參數調整碼率。

預設值:32。

取值範圍:[6, 510]。

bit_rate需要通過parameters字典進行設定:

audio = client.audio.tts.synthesize(
    "待合成文本",
    model="cosyvoice-v3-plus",
    voice="longanyang",
    parameters={"bit_rate": 128},
)
word_timestamp_enabledbool否是否開啟字層級時間戳記。

預設值:false。

僅在流式輸出模式下可用。支援的音色範圍:cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2模型的複刻音色,以及CosyVoice音色列表中標記為支援的系統音色。其他模型的複刻音色不支援此功能。

word_timestamp_enabled需要通過parameters字典進行設定:

audio = client.audio.tts.stream(
    "待合成文本",
    model="cosyvoice-v3-flash",
    voice="your_voice",  # 支援字層級時間戳記的系統音色或複刻音色
    parameters={"word_timestamp_enabled": True},
)
seedint否產生時使用的隨機數種子,使合成的效果產生變化。在模型版本、文本、音色及其他參數均相同的前提下,使用相同的seed可複現相同的合成結果。

預設值0。

取值範圍:[0, 65535]。

language_hintslist[str]否

重要

  • 此參數為數組,但目前的版本僅處理第一個元素,因此建議只傳入一個值。
  • 此參數用於指定語音合成的目標語言,該設定與聲音複刻時的樣本音訊語種無關。如需設定複刻任務的源語言,請參見聲音複刻API參考。

指定語音合成的目標語言,提升合成效果。

當數字、縮寫、符號等朗讀方式或者小語種合成效果不符合預期時使用,例如:

  • 數字朗讀方式不符合預期,“hello, this is 110”讀成“hello, this is one one zero”而非“hello, this is 么么零”
  • 符號朗讀不準確,“@”讀成“艾特”而非“at”
  • 小語種合成效果差,合成不自然

取值範圍

  • zh:中文
  • en:英語
  • fr:法語
  • de:德語
  • ja:日語
  • ko:韓語
  • ru:俄語
  • pt:葡萄牙語
  • th:泰語
  • id:印尼語
  • vi:越南語
  • es:西班牙語
  • it:意大利語
  • ms:馬來語
  • fil:菲律賓語
  • ar:阿拉伯語
instructionstr否設定指令,用於控制方言、情感或角色等合成效果。

使用說明請參見指令控制。

enable_aigc_tagbool否是否在產生的音頻中添加AIGC隱性標識。設定為true時,會將隱性標識嵌入到支援格式(wav/mp3/opus)的音頻中。

預設值:false。

說明僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。

enable_aigc_tag、aigc_propagator和aigc_propagate_id需要通過parameters字典進行設定:

audio = client.audio.tts.synthesize(
    "待合成文本",
    model="cosyvoice-v3-plus",
    voice="longanyang",
    parameters={
        "enable_aigc_tag": True,
        "aigc_propagator": "your_propagator",
        "aigc_propagate_id": "your_propagate_id"
    },
)
aigc_propagatorstr否設定AIGC隱性標識中的 ContentPropagator 欄位,用於標識內容的傳播者。僅在 enable_aigc_tag 為 true 時生效。

預設值:阿里雲UID。

說明僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。

需要通過parameters字典進行設定,參見enable_aigc_tag的樣本。

aigc_propagate_idstr否設定AIGC隱性標識中的 PropagateID 欄位,用於唯一標識一次具體的傳播行為。僅在 enable_aigc_tag 為 true 時生效。

預設值:本次語音合成請求Request ID。

說明僅cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2支援該功能。

需要通過parameters字典進行設定,參見enable_aigc_tag的樣本。

hot_fixdict否文本熱修複配置,用於自訂指定詞語的發音或對待合成文本進行替換。

說明cosyvoice-v2不支援該功能。

參數介紹:

  • pronunciation:自訂發音。指定詞語的拼音標註,用於糾正預設發音不準確的情況。
  • replace:文本替換。在語音合成前將指定詞語替換為目標文本,替換後的文本將作為實際合成內容。

樣本:

audio = client.audio.tts.synthesize(
    "待合成文本",
    model="cosyvoice-v3.5-plus",
    voice="cosyvoice-v3.5-plus-vd-announcer-xxxxxx", # 音色
    parameters={
        "hot_fix": {
            "pronunciation": [{"天氣": "tian1 qi4"}],
            "replace": [{"今天": "金天"}]
        }
    },
)
enable_markdown_filterbool否

說明cosyvoice-v2 不支援此功能。

是否啟用 Markdown 過濾。啟用後,服務會在合成前將 Markdown 轉換為適合朗讀的文字。

預設值:false。

取值範圍:

  • true:啟用Markdown過濾
  • false:禁用Markdown過濾

enable_markdown_filter需要通過parameters字典進行設定:

audio = client.audio.tts.synthesize(
    "待合成文本",
    model="cosyvoice-v3-flash",
    voice="your_voice",  # cosyvoice-v3-flash複刻音色
    parameters={"enable_markdown_filter": True},
)

介面參考

核心資源(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]

參數說明:

參數類型必填說明
textstr是待合成的完整文本,長度不得超過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欄位的結構說明:

欄位類型說明
typestr事件類型。取值為sentence-begin(句子合成開始)、sentence-synthesis(句子合成中)或sentence-end(句子合成結束)。
original_textstr當前句子的原始文本。在sentence-begin和sentence-end事件中返回。
sentencedict句子資訊。包含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

共用說明

請參閱新版 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

參數說明:

參數類型必填說明
textstr是待合成的完整文本,長度不得超過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

共用說明

請參閱新版 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

參數說明:

參數類型必填說明
textstr是待合成的完整文本,長度不得超過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)