全部產品
Search
文件中心

Alibaba Cloud Model Studio:語音合成CosyVoice Python SDK

更新時間:Dec 10, 2025

本文介紹語音合成CosyVoice Python SDK的參數和介面細節。

重要

本文檔僅適用於“中國大陸(北京)”地區。如需使用模型,需使用“中國大陸(北京)”地區的API Key

使用者指南:關於模型介紹和選型建議請參見即時語音合成-CosyVoice/Sambert

前提條件

  • 已開通服務並擷取與配置 API Key。請配置API Key到環境變數(準備下線,併入配置 API Key),而非寫入程式碼在代碼中,防範因代碼泄露導致的安全風險。

    說明

    當您需要為第三方應用或使用者提供臨時存取權限,或者希望嚴格控制敏感性資料訪問、刪除等高風險操作時,建議使用臨時鑒權Token

    與長期有效 API Key 相比,臨時鑒權 Token 具備時效性短(60秒)、安全性高的特點,適用於臨時調用情境,能有效降低API Key泄露的風險。

    使用方式:在代碼中,將原本用於鑒權的 API Key 替換為擷取到的臨時鑒權 Token 即可。

  • 安裝最新版DashScope SDK

模型與價格

模型名稱

單價

cosyvoice-v3-plus

$0.286706/萬字元

cosyvoice-v3-flash

$0.14335/萬字元

cosyvoice-v2

$0.286706/萬字元

語音合成文本限制與格式規範

文本長度限制

  • 非流式調用(同步調用非同步呼叫):單次發送文本長度不得超過 2000 字元。

  • 流式調用:單次發送文本長度不得超過 2000 字元,且累計發送文本總長度不得超過 20 萬字元。

字元計算規則

  • 漢字(包括簡/繁體漢字、日文漢字和韓文漢字)按2個字元計算,其他所有字元(如標點符號、字母、數字、日韓文假名/諺文等)均按 1個字元計算

  • 計算文本長度時,不包含SSML 標籤內容

  • 樣本:

    • "你好" → 2(你)+2(好)=4字元

    • "中A文123" → 2(中)+1(A)+2(文)+1(1)+1(2)+1(3)=8字元

    • "中文。" → 2(中)+2(文)+1(。)=5字元

    • "中 文。" → 2(中)+1(空格)+2(文)+1(。)=6字元

    • "<speak>你好</speak>" → 2(你)+2(好)=4字元

編碼格式

需採用UTF-8編碼。

數學運算式支援說明

當前數學運算式解析功能僅適用於cosyvoice-v2cosyvoice-v3-flashcosyvoice-v3-plus模型,支援識別中小學常見的數學運算式,包括但不限於基礎運算、代數、幾何等內容。

詳情請參見LaTeX 方程式轉語音

SSML標記語言支援說明

當前SSML(Speech Synthesis Markup Language,語音合成標記語言)功能僅cosyvoice-v3-plus、cosyvoice-v3-flash和cosyvoice-v2模型的部分音色可用,使用時需滿足以下條件:

快速開始

SpeechSynthesizer類提供了語音合成的關鍵介面,支援以下幾種調用方式:

  • 同步調用:阻塞式,一次性發送完整文本,直接返回完整音頻。適合短文本語音合成情境。

  • 非同步呼叫:非阻塞式,一次性發送完整文本,通過回呼函數接收音頻資料(可能分區)。適用於對即時性要求高的短文本語音合成情境。

  • 流式調用:非阻塞式,可分多次發送文本片段,通過回呼函數即時接收增量合成的音頻流。適合即時性要求高的長文本語音合成情境。

同步調用

提交單個語音合成任務,無需調用回呼函數,進行語音合成(無流式輸出中間結果),最終一次性擷取完整結果。

執行個體化SpeechSynthesizer類綁定請求參數,調用call方法進行合成並擷取二進位音頻資料。

發送的文本長度不得超過2000字元(詳情請參見SpeechSynthesizer類call方法)。

重要

每次調用call方法前,需要重新初始化SpeechSynthesizer執行個體。

點擊查看完整樣本

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *

# 若沒有將API Key配置到環境變數中,需將your-api-key替換為自己的API Key
# dashscope.api_key = "your-api-key"

# 模型
model = "cosyvoice-v2"
# 音色
voice = "longxiaochun_v2"

# 執行個體化SpeechSynthesizer,並在構造方法中傳入模型(model)、音色(voice)等請求參數
synthesizer = SpeechSynthesizer(model=model, voice=voice)
# 發送待合成文本,擷取二進位音頻
audio = synthesizer.call("今天天氣怎麼樣?")
# 首次發送文本時需建立 WebSocket 串連,因此首包延遲會包含串連建立的耗時
print('[Metric] requestId為:{},首包延遲為:{}毫秒'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

# 將音頻儲存至本地
with open('output.mp3', 'wb') as f:
    f.write(audio)

非同步呼叫

提交單個語音合成任務,通過回調的方式流式輸出中間結果,合成結果通過ResultCallback中的回呼函數流式擷取。

執行個體化SpeechSynthesizer類綁定請求參數回調介面(ResultCallback),調用call方法進行合成並通過回調介面(ResultCallback)on_data方法即時擷取合成結果。

發送的文本長度不得超過2000字元(詳情請參見SpeechSynthesizer類call方法)。

重要

每次調用call方法前,需要重新初始化SpeechSynthesizer執行個體。

點擊查看完整樣本

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *

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配置到環境變數中,需將your-api-key替換為自己的API Key
# dashscope.api_key = "your-api-key"

# 模型
model = "cosyvoice-v2"
# 音色
voice = "longxiaochun_v2"


# 定義回調介面
class Callback(ResultCallback):
    _player = None
    _stream = None

    def on_open(self):
        self.file = open("output.mp3", "wb")
        print("串連建立:" + get_timestamp())

    def on_complete(self):
        print("語音合成完成,所有合成結果已被接收:" + get_timestamp())

    def on_error(self, message: str):
        print(f"語音合成出現異常:{message}")

    def on_close(self):
        print("串連關閉:" + get_timestamp())
        self.file.close()

    def on_event(self, message):
        pass

    def on_data(self, data: bytes) -> None:
        print(get_timestamp() + " 二進位音頻長度為:" + str(len(data)))
        self.file.write(data)


callback = Callback()

# 執行個體化SpeechSynthesizer,並在構造方法中傳入模型(model)、音色(voice)等請求參數
synthesizer = SpeechSynthesizer(
    model=model,
    voice=voice,
    callback=callback,
)

# 發送待合成文本,在回調介面的on_data方法中即時擷取二進位音頻
synthesizer.call("今天天氣怎麼樣?")
# 首次發送文本時需建立 WebSocket 串連,因此首包延遲會包含串連建立的耗時
print('[Metric] requestId為:{},首包延遲為:{}毫秒'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

流式調用

在同一個語音合成任務中分多次提交文本,並通過回調的方式即時擷取合成結果。

說明
  • 流式輸入時可多次調用streaming_call按順序提交文本片段。服務端接收文本片段後自動進行分句:

    • 完整語句立即合成

    • 不完整語句緩衝至完整後合成

    調用 streaming_complete 時,服務端會強制合成所有已接收但未處理的文本片段(包括未完成的句子)。

  • 發送文本片段的間隔不得超過23秒,否則觸發“request timeout after 23 seconds”異常。

    若無待發送文本,需及時調用 streaming_complete結束任務。

    服務端強制設定23秒逾時機制,用戶端無法修改該配置。
  1. 執行個體化SpeechSynthesizer類

    執行個體化SpeechSynthesizer類綁定請求參數回調介面(ResultCallback)

  2. 串流

    多次調用SpeechSynthesizer類streaming_call方法分區提交待合成文本,將待合成文本分段發送至服務端。

    在發送文本的過程中,服務端會通過回調介面(ResultCallback)on_data方法,將合成結果即時返回給用戶端。

    每次調用streaming_call方法發送的文本片段(即text)長度不得超過2000字元,累計發送的文本總長度不得超過20萬字元。

  3. 結束處理

    調用SpeechSynthesizer類streaming_complete方法結束語音合成。

    該方法會阻塞當前線程,直到回調介面(ResultCallback)on_complete或者on_error回調觸發後才會釋放線程阻塞。

    請務必確保調用該方法,否則可能會導致結尾部分的文本無法成功轉換為語音。

點擊查看完整樣本

# 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 time
import pyaudio
import dashscope
from dashscope.api_entities.dashscope_response import SpeechSynthesisResponse
from dashscope.audio.tts_v2 import *

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配置到環境變數中,需將your-api-key替換為自己的API Key
# dashscope.api_key = "your-api-key"

# 模型
model = "cosyvoice-v2"
# 音色
voice = "longxiaochun_v2"


# 定義回調介面
class Callback(ResultCallback):
    _player = None
    _stream = None

    def on_open(self):
        print("串連建立:" + get_timestamp())
        self._player = pyaudio.PyAudio()
        self._stream = self._player.open(
            format=pyaudio.paInt16, channels=1, rate=22050, output=True
        )

    def on_complete(self):
        print("語音合成完成,所有合成結果已被接收:" + get_timestamp())

    def on_error(self, message: str):
        print(f"語音合成出現異常:{message}")

    def on_close(self):
        print("串連關閉:" + get_timestamp())
        # 停止播放器
        self._stream.stop_stream()
        self._stream.close()
        self._player.terminate()

    def on_event(self, message):
        pass

    def on_data(self, data: bytes) -> None:
        print(get_timestamp() + " 二進位音頻長度為:" + str(len(data)))
        self._stream.write(data)


callback = Callback()

test_text = [
    "流式文本語音合成SDK,",
    "可以將輸入的文本",
    "合成為語音位元據,",
    "相比於非流式語音合成,",
    "流式合成的優勢在於即時性",
    "更強。使用者在輸入文本的同時",
    "可以聽到接近同步的語音輸出,",
    "極大地提升了互動體驗,",
    "減少了使用者等待時間。",
    "適用於調用大規模",
    "語言模型(LLM),以",
    "流式輸入文本的方式",
    "進行語音合成的情境。",
]

# 執行個體化SpeechSynthesizer,並在構造方法中傳入模型(model)、音色(voice)等請求參數
synthesizer = SpeechSynthesizer(
    model=model,
    voice=voice,
    format=AudioFormat.PCM_22050HZ_MONO_16BIT,  
    callback=callback,
)


# 流式發送待合成文本。在回調介面的on_data方法中即時擷取二進位音頻
for text in test_text:
    synthesizer.streaming_call(text)
    time.sleep(0.1)
# 結束流式語音合成
synthesizer.streaming_complete()

# 首次發送文本時需建立 WebSocket 串連,因此首包延遲會包含串連建立的耗時
print('[Metric] requestId為:{},首包延遲為:{}毫秒'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

請求參數

請求參數通過SpeechSynthesizer類的構造方法進行設定。

參數

類型

預設值

是否必須

說明

model

str

-

指定模型。

不同版本的模型編碼方式一致,但使用時須確保模型(model)與音色(voice)匹配:每個版本的模型只能使用本版本的預設音色或專屬音色。

voice

str

-

指定語音合成所使用的音色。

支援預設音色和專屬音色:

⚠️ 使用聲音複刻系列模型合成語音時,僅能使用該模型複刻產生的專屬音色,不能使用預設音色。

⚠️ 使用專屬音色合成語音時,語音合成模型(model)必須與聲音複刻模型(target_model)相同。

format

enum

mp3

指定音頻編碼格式及採樣率。

若未指定format,則合成音頻採樣率為22.05kHz,格式為mp3。

說明

預設採樣率代表當前音色的最佳採樣率,預設條件下預設按照該採樣率輸出,同時支援降採樣或升採樣。

可指定的音頻編碼格式及採樣率如下:

  • 所有模型均支援的音頻編碼格式及採樣率:

    • AudioFormat.WAV_8000HZ_MONO_16BIT,代表音頻格式為wav,採樣率為8kHz

    • AudioFormat.WAV_16000HZ_MONO_16BIT,代表音頻格式為wav,採樣率為16kHz

    • AudioFormat.WAV_22050HZ_MONO_16BIT,代表音頻格式為wav,採樣率為22.05kHz

    • AudioFormat.WAV_24000HZ_MONO_16BIT,代表音頻格式為wav,採樣率為24kHz

    • AudioFormat.WAV_44100HZ_MONO_16BIT,代表音頻格式為wav,採樣率為44.1kHz

    • AudioFormat.WAV_48000HZ_MONO_16BIT,代表音頻格式為wav,採樣率為48kHz

    • AudioFormat.MP3_8000HZ_MONO_128KBPS,代表音頻格式為mp3,採樣率為8kHz

    • AudioFormat.MP3_16000HZ_MONO_128KBPS,代表音頻格式為mp3,採樣率為16kHz

    • AudioFormat.MP3_22050HZ_MONO_256KBPS,代表音頻格式為mp3,採樣率為22.05kHz

    • AudioFormat.MP3_24000HZ_MONO_256KBPS,代表音頻格式為mp3,採樣率為24kHz

    • AudioFormat.MP3_44100HZ_MONO_256KBPS,代表音頻格式為mp3,採樣率為44.1kHz

    • AudioFormat.MP3_48000HZ_MONO_256KBPS,代表音頻格式為mp3,採樣率為48kHz

    • AudioFormat.PCM_8000HZ_MONO_16BIT,代表音頻格式為pcm,採樣率為8kHz

    • AudioFormat.PCM_16000HZ_MONO_16BIT,代表音頻格式為pcm,採樣率為16kHz

    • AudioFormat.PCM_22050HZ_MONO_16BIT,代表音頻格式為pcm,採樣率為22.05kHz

    • AudioFormat.PCM_24000HZ_MONO_16BIT,代表音頻格式為pcm,採樣率為24kHz

    • AudioFormat.PCM_44100HZ_MONO_16BIT,代表音頻格式為pcm,採樣率為44.1kHz

    • AudioFormat.PCM_48000HZ_MONO_16BIT,代表音頻格式為pcm,採樣率為48kHz

  • 音頻格式為opus時,支援通過bit_rate參數調整碼率。僅對1.24.0及之後版本的DashScope適用。

    • AudioFormat.OGG_OPUS_8KHZ_MONO_32KBPS,代表音頻格式為opus,採樣率為8kHz,碼率為32kbps

    • AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,代表音頻格式為opus,採樣率為16kHz,碼率為16kbps

    • AudioFormat.OGG_OPUS_16KHZ_MONO_32KBPS,代表音頻格式為opus,採樣率為16kHz,碼率為32kbps

    • AudioFormat.OGG_OPUS_16KHZ_MONO_64KBPS,代表音頻格式為opus,採樣率為16kHz,碼率為64kbps

    • AudioFormat.OGG_OPUS_24KHZ_MONO_16KBPS,代表音頻格式為opus,採樣率為24kHz,碼率為16kbps

    • AudioFormat.OGG_OPUS_24KHZ_MONO_32KBPS,代表音頻格式為opus,採樣率為24kHz,碼率為32kbps

    • AudioFormat.OGG_OPUS_24KHZ_MONO_64KBPS,代表音頻格式為opus,採樣率為24kHz,碼率為64kbps

    • AudioFormat.OGG_OPUS_48KHZ_MONO_16KBPS,代表音頻格式為opus,採樣率為48kHz,碼率為16kbps

    • AudioFormat.OGG_OPUS_48KHZ_MONO_32KBPS,代表音頻格式為opus,採樣率為48kHz,碼率為32kbps

    • AudioFormat.OGG_OPUS_48KHZ_MONO_64KBPS,代表音頻格式為opus,採樣率為48kHz,碼率為64kbps

volume

int

50

合成音訊音量,取值範圍:0~100。

重要

該欄位在不同版本的DashScope SDK中有所不同:

  • 1.20.10及以後版本的SDK:volume

  • 1.20.10以前版本的SDK:volumn

speech_rate

float

1.0

合成音訊語速,取值範圍:0.5~2。

  • 0.5:表示預設語速的0.5倍速。

  • 1:表示預設語速。預設語速是指模型預設輸出的合成語速,語速會因音色不同而略有不同。約每秒鐘4個字。

  • 2:表示預設語速的2倍速。

pitch_rate

float

1.0

合成音訊語調,取值範圍:0.5~2。

bit_rate

int

32

指定音訊碼率,取值範圍:6~510kbps。

碼率越大,音質越好,音頻檔案體積越大。

僅在音頻格式(format)為opus時可用。

說明

bit_rate需要通過additional_params參數進行設定:

synthesizer = SpeechSynthesizer(model="cosyvoice-v2",
                                voice="longxiaochun_v2",
                                format=AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,
                                additional_params={"bit_rate": 32})

word_timestamp_enabled

bool

False

是否開啟字層級時間戳記,預設關閉。

僅cosyvoice-v2支援該功能。

時間戳記結果僅能通過回調介面擷取
說明

word_timestamp_enabled需要通過additional_params參數進行設定:

synthesizer = SpeechSynthesizer(model="cosyvoice-v2",
                                voice="longxiaochun_v2",
                                callback=callback, # 時間戳記結果僅能通過回調介面擷取
                                additional_params={'word_timestamp_enabled': True})

點擊查看完整範例程式碼

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *
import json
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配置到環境變數中,需將your-api-key替換為自己的API Key
# dashscope.api_key = "your-api-key"

# 模型僅支援cosyvoice-v2
model = "cosyvoice-v2"
# 音色
voice = "longxiaochun_v2"


# 定義回調介面
class Callback(ResultCallback):
    _player = None
    _stream = None

    def on_open(self):
        self.file = open("output.mp3", "wb")
        print("串連建立:" + get_timestamp())

    def on_complete(self):
        print("語音合成完成,所有合成結果已被接收:" + get_timestamp())

    def on_error(self, message: str):
        print(f"語音合成出現異常:{message}")

    def on_close(self):
        print("串連關閉:" + get_timestamp())
        self.file.close()

    def on_event(self, message):
        json_data = json.loads(message)
        if json_data['payload'] and json_data['payload']['output'] and json_data['payload']['output']['sentence']:
            sentence = json_data['payload']['output']['sentence']
            print(f'sentence: {sentence}')
            # 擷取句子的編號
            # index = sentence['index']
            words = sentence['words']
            if words:
                for word in words:
                    print(f'word: {word}')
                    # 樣本值:word: {'text': '今', 'begin_index': 0, 'end_index': 1, 'begin_time': 80, 'end_time': 200}

    def on_data(self, data: bytes) -> None:
        print(get_timestamp() + " 二進位音頻長度為:" + str(len(data)))
        self.file.write(data)


callback = Callback()

# 執行個體化SpeechSynthesizer,並在構造方法中傳入模型(model)、音色(voice)等請求參數
synthesizer = SpeechSynthesizer(
    model=model,
    voice=voice,
    callback=callback,
    additional_params={'word_timestamp_enabled': True}
)

# 發送待合成文本,在回調介面的on_data方法中即時擷取二進位音頻
synthesizer.call("今天天氣怎麼樣?")
# 首次發送文本時需建立 WebSocket 串連,因此首包延遲會包含串連建立的耗時
print('[Metric] requestId為:{},首包延遲為:{}毫秒'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

seed

int

0

產生時使用的隨機數種子,使合成的效果產生變化。預設值0。取值範圍:0~65535。

language_hints

list[str]

-

提供語言提示,僅cosyvoice-v3-flash、cosyvoice-v3-plus支援該功能。

在語音合成中有如下作用:

  1. 指定 TN(Text Normalization,文本正常化)處理所用的語言,影響數字、縮寫、符號等的朗讀方式(僅中文、英文生效)。

    取值範圍:

    • zh:中文

    • en:英文

  2. 指定語音合成的目標語言(僅限複刻音色),協助提升合成效果準確性,對英文、法語、德語、日語、韓語、俄語生效(無需填寫中文)。須和聲音複刻時使用的languageHints/language_hints一致。

    取值範圍:

    • en:英文

    • fr:法語

    • de:德語

    • ja:日語

    • ko:韓語

    • ru:俄語

若設定的語言提示與常值內容明顯不符(如為中文文本設定en),將忽略此提示,並依據常值內容自動檢測語言。

注意:此參數為數組,但目前的版本僅處理第一個元素,因此建議只傳入一個值。

instruction

str

-

設定提示詞。僅cosyvoice-v3-flash、cosyvoice-v3-plus支援該功能。

在語音合成中有如下作用:

  1. 指定小語種(僅限複刻音色)

    • 格式:“你會用<小語種>說出來。”(注意,結尾一定不要遺漏句號,使用時將“<小語種>”替換為具體的小語種,例如替換為德語)。

    • 樣本:“你會用德語說出來。

    • 支援的小語種:法語、德語、日語、韓語、俄語。

  2. 指定方言(僅限複刻音色)

    • 格式:“請用<方言>表達。”(注意,結尾一定不要遺漏句號,使用時將“<方言>”替換為具體的方言,例如替換為廣東話)。

    • 樣本:“請用廣東話表達。

    • 支援的方言:廣東話、東北話、甘肅話、貴州話、河南話、湖北話、江西話、閩南話、寧夏話、山西話、陝西話、山東話、上海話、四川話、天津話、雲南話。

  3. 指定情感、情境、角色或身份等:僅部分預設音色支援該功能,且因音色而異,詳情請參見音色列表

enable_aigc_tag

bool

False

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

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

說明

enable_aigc_tag需要通過additional_params參數進行設定:

synthesizer = SpeechSynthesizer(model="cosyvoice-v2",
                                voice="longxiaochun_v2",
                                format=AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,
                                additional_params={"enable_aigc_tag": True})

aigc_propagator

str

阿里雲UID

設定AIGC隱性標識中的 ContentPropagator 欄位,用於標識內容的傳播者。僅在 enable_aigc_tag 為 true 時生效。

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

說明

aigc_propagator需要通過additional_params參數進行設定:

synthesizer = SpeechSynthesizer(model="cosyvoice-v2",
                                voice="longxiaochun_v2",
                                format=AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,
                                additional_params={"enable_aigc_tag": True, "aigc_propagator": "xxxx"})

aigc_propagate_id

str

本次語音合成請求Request ID

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

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

說明

aigc_propagate_id需要通過additional_params參數進行設定:

synthesizer = SpeechSynthesizer(model="cosyvoice-v2",
                                voice="longxiaochun_v2",
                                format=AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,
                                additional_params={"enable_aigc_tag": True, "aigc_propagate_id": "xxxx"})

callback

ResultCallback

-

回調介面(ResultCallback).

關鍵介面

SpeechSynthesizer

SpeechSynthesizer通過“from dashscope.audio.tts_v2 import *”方式引入,提供語音合成的關鍵介面。

方法

參數

傳回值

描述

def call(self, text: str, timeout_millis=None)
  • text:待合成文本

  • timeout_millis:阻塞線程的逾時時間,單位為毫秒,不設定或值為0時不生效

沒有指定ResultCallback時返回二進位音頻資料,否則返回None

將整段文本(無論是純文字還是包含SSML的文本)轉換為語音。

在建立SpeechSynthesizer執行個體時,存在以下兩種情況:

  • 沒有指定ResultCallbackcall方法會阻塞當前線程直到語音合成完成並返回二進位音頻資料。使用方法請參見同步調用

  • 指定了ResultCallbackcall方法會立刻返回None,並通過回調介面(ResultCallback)on_data方法返回語音合成的結果。使用方法請參見非同步呼叫

重要

每次調用call方法前,需要重新初始化SpeechSynthesizer執行個體。

def streaming_call(self, text: str)

text:待合成文本片段

流式發送待合成文本(不支援包含SSML的文本)。

您可以多次調用該介面,將待合成文本分多次發送給服務端。合成結果通過回調介面(ResultCallback)on_data方法擷取。

使用方法請參見流式調用

def streaming_complete(self, complete_timeout_millis=600000)

complete_timeout_millis:等待時間,單位為毫秒

結束流式語音合成。

該方法阻塞當前線程N毫秒(具體時間長度由complete_timeout_millis決定),直到任務結束。如果completeTimeoutMillis設定為0,則無限期等待。

預設情況下,如果等待時間超過10分鐘,則停止等待。

使用方法請參見流式調用

重要

流式調用時,請務必確保調用該方法,否則可能會出現合成語音缺失的問題。

def get_last_request_id(self)

上一個任務的request_id

擷取上一個任務的request_id。

def get_first_package_delay(self)

首包延遲

擷取首包延遲(一般在500ms左右)。

首包延遲是開始發送文本和接收第一個音頻包之間的時間,單位為毫秒。在任務完成後使用。

首次發送文本時需建立 WebSocket 串連,因此首包延遲會包含串連建立的耗時。

def get_response(self)

最後一次報文

擷取最後一次報文(為JSON格式的資料),可以用於擷取task-failed報錯。

回調介面(ResultCallback

非同步呼叫流式調用時,服務端會通過回調的方式,將關鍵流程資訊和資料返回給用戶端。您需要實現回調方法,處理服務端返回的資訊或者資料。

通過“from dashscope.audio.tts_v2 import *”方式引入。

點擊查看樣本

class Callback(ResultCallback):
    def on_open(self) -> None:
        print('串連成功')
    
    def on_data(self, data: bytes) -> None:
        # 實現接收合成二進位音頻結果的邏輯

    def on_complete(self) -> None:
        print('合成完成')

    def on_error(self, message) -> None:
        print('出現異常:', message)

    def on_close(self) -> None:
        print('串連關閉')


callback = Callback()

方法

參數

傳回值

描述

def on_open(self) -> None

當和服務端建立串連完成後,該方法立刻被回調。

def on_event( self, message: str) -> None

message:服務端返回的資訊

當服務有回複時會被回調。message為JSON字串,解析可擷取Task ID(task_id參數)、本次請求中計費的有效字元數(characters參數)等資訊。

def on_complete(self) -> None

當所有合成資料全部返回(語音合成完成)後被回調。

def on_error(self, message) -> None

message:異常資訊

發生異常時該方法被回調。

def on_data(self, data: bytes) -> None

data:伺服器返回的二進位音頻資料

當伺服器有合成音頻返回時被回調。

您可以將二進位音頻資料合成為一個完整的音頻檔案後使用播放器播放,也可以通過支援流式播放的播放器即時播放。

重要
  • 流式語音合成中,對於mp3/opus等壓縮格式,音頻分段傳輸需使用流式播放器,不可逐幀播放,避免解碼失敗。

    支援流式播放的播放器:ffmpeg、pyaudio (Python)、AudioFormat (Java)、MediaSource (Javascript)等。
  • 將音頻資料合成完整的音頻檔案時,應以追加模式寫入同一檔案。

  • 流式語音合成的wav/mp3 格式音頻僅首幀包含頭資訊,後續幀為純音頻資料。

def on_close(self) -> None

當服務已經關閉串連後被回調。

響應結果

伺服器返回二進位音頻資料:

錯誤碼

如遇報錯問題,請參見錯誤資訊進行排查。

更多樣本

更多樣本,請參見GitHub

常見問題

功能特性/計量計費/限流

Q:當遇到發音不準的情況時,有什麼解決方案可以嘗試?

通過SSML可以對語音合成效果進行個人化定製。

Q:語音合成是按文本字元數計費的,要如何查看或擷取每次合成的文本長度?

根據是否開啟日誌,有不同的擷取方式:

  1. 未開啟日誌

    • 同步調用:需要按照字元計算規則自行計算。

    • 其他調用方式:通過回調介面(ResultCallback)on_event方法的message參數擷取。message為JSON字串,解析可擷取本次請求中計費的有效字元數(characters參數)。請以收到的最後一個message為準。

  2. 開啟日誌

    在控制台會列印如下日誌,characters即為本次請求中計費的有效字元數。請以列印的最後一個日誌為準。

    2025-08-27 11:02:09,429 - dashscope - speech_synthesizer.py - on_message - 454 - DEBUG - <<<recv {"header":{"task_id":"62ebb7d6cb0a4080868f0edb######","event":"result-generated","attributes":{}},"payload":{"output":{"sentence":{"words":[]}},"usage":{"characters":15}}}

點擊查看如何開啟日誌

通過在命令列設定環境變數開啟日誌:

  • Windows系統:$env:DASHSCOPE_LOGGING_LEVEL="debug"

  • Linux/macOS系統:export DASHSCOPE_LOGGING_LEVEL=debug

故障排查

如遇代碼報錯問題,請根據錯誤碼中的資訊進行排查。

Q:如何擷取Request ID

通過以下兩種方式可以擷取:

Q:使用SSML功能失敗是什麼原因?

請按以下步驟排查:

  1. 確保當前音色支援SSML功能(聲音複刻音色不支援SSML)

  2. 確保model參數值為cosyvoice-v2

  3. 安裝最新版本 DashScope SDK

  4. 確保使用正確的介面:只有SpeechSynthesizer類call方法支援SSML

  5. 確保待合成文本為純文字格式且符合格式要求,詳情請參見SSML標記語言介紹

Q:為什麼音頻無法播放?

請根據以下情境逐一排查:

  1. 音頻儲存為完整檔案(如xx.mp3)的情況

    1. 音頻格式一致性:確保請求參數中設定的音頻格式與檔案尾碼一致。例如,如果請求參數設定的音頻格式為wav,但檔案尾碼為mp3,可能會導致播放失敗。

    2. 播放器相容性:確認使用的播放器是否支援該音頻檔案的格式和採樣率。例如,某些播放器可能不支援高採樣率或特定編碼的音頻檔案。

  2. 流式播放音訊情況

    1. 將音頻流儲存為完整檔案,嘗試使用播放器播放。如果檔案無法播放,請參考情境 1 的排查方法。

    2. 如果檔案可以正常播放,則問題可能出在流式播放的實現上。請確認使用的播放器是否支援流式播放。

      常見的支援流式播放的工具和庫包括:ffmpeg、pyaudio (Python)、AudioFormat (Java)、MediaSource (Javascript)等。

Q:為什麼音頻播放卡頓?

請根據以下情境逐一排查:

  1. 檢查文本發送速度: 確保發送文本的間隔合理,避免前一句音頻播放完畢後,下一句文本未能及時發送。

  2. 檢查回呼函數效能:

    • 檢查回呼函數中是否存在過多商務邏輯,導致阻塞。

    • 回呼函數運行在 WebSocket 線程中,若被阻塞,可能會影響 WebSocket 接收網路資料包,進而導致音頻接收卡頓。

    • 建議將音頻資料寫入一個獨立的音頻緩衝區(audio buffer),然後在其他線程中讀取並處理,避免阻塞 WebSocket 線程。

  3. 檢查網路穩定性: 確保網路連接穩定,避免因網路波動導致音頻傳輸中斷或延遲。

Q:語音合成慢(合成時間長)是什麼原因?

請按以下步驟排查:

  1. 檢查輸入間隔

    如果是流式語音合成,請確認文字發送間隔是否過長(如上段發出後延遲數秒才發送下段),過久間隔會導致合成總時間長度增加。

  2. 分析效能指標

    • 首包延遲:正常500ms左右。

    • RTF(RTF = 合成總耗時/音頻時間長度):正常小於1.0。

Q:合成的語音發音錯誤如何處理?

  • 若當前使用的模型為cosyvoice-v1,推薦使用cosyvoice-v2,v2效果更好且支援SSML

  • 若當前使用的模型為cosyvoice-v2,請使用SSML的<phoneme>標籤指定正確的發音。

Q:為什麼沒有返回語音?為什麼結尾部分的文本沒能成功轉換成語音?(合成語音缺失)

請檢查是否遺漏了調用SpeechSynthesizer類streaming_complete方法。在語音合成過程中,服務端會在緩衝足夠文本後才開始合成。如果未調用streaming_complete方法,可能會導致緩衝中的結尾部分文本未能被合成為語音。

Q:SSL認證校正失敗如何處理?

  1. 安裝系統根憑證

    sudo yum install -y ca-certificates
    sudo update-ca-trust enable
  2. 代碼中添加如下內容

    import os
    os.environ["SSL_CERT_FILE"] = "/etc/ssl/certs/ca-bundle.crt"

Q:Mac環境下出現“SSL: CERTIFICATE_VERIFY_FAILED”異常是什麼原因?(websocket closed due to [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000))

在串連 WebSocket 時,可能會遇到 OpenSSL 驗證認證失敗的問題,提示找不到認證。這通常是由於 Python 環境的認證配置不正確導致的。可以通過以下步驟手動定位並修複認證問題:

  1. 匯出系統認證並設定環境變數 執行以下命令,將 macOS 系統中的所有認證匯出到一個檔案,並將其設定為 Python 和相關庫的預設憑證路徑:

    security find-certificate -a -p > ~/all_mac_certs.pem
    export SSL_CERT_FILE=~/all_mac_certs.pem
    export REQUESTS_CA_BUNDLE=~/all_mac_certs.pem
  2. 建立符號連結以修複 Python 的 OpenSSL 配置 如果 Python 的 OpenSSL 配置缺失認證,可以通過以下命令手動建立符號連結。請確保替換命令中的路徑為本地 Python 版本的實際安裝目錄:

    # 3.9是樣本版本號碼,請根據您本地安裝的 Python 版本調整路徑
    ln -s /etc/ssl/* /Library/Frameworks/Python.framework/Versions/3.9/etc/openssl
  3. 重新啟動終端並清除緩衝 完成上述操作後,請關閉並重新開啟終端,以確保環境變數生效。清除可能的緩衝後重試串連 WebSocket。

通過以上步驟,可以解決因認證配置錯誤導致的串連問題。如果問題仍未解決,請檢查目標伺服器的認證配置是否正確。

Q:運行代碼提示“AttributeError: module 'websocket' has no attribute 'WebSocketApp'. Did you mean: 'WebSocket'?”是什麼原因?

原因是沒有安裝websocket-client或websocket-client版本不匹配,請依次執行以下命令:

pip uninstall websocket-client
pip uninstall websocket
pip install websocket-client

許可權與認證

Q:我希望我的 API Key 僅用於 CosyVoice 語音合成服務,而不被百鍊其他模型使用(許可權隔離),我該如何做

可以通過建立業務空間並只授權特定模型來限制API Key的使用範圍。詳情請參見業務空間管理

更多問題

請參見GitHub QA