全部產品
Search
文件中心

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

更新時間:Mar 01, 2026

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

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

前提條件

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

    說明

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

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

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

  • 安裝最新版DashScope SDK

模型與價格

參見即時語音合成-CosyVoice/Sambert

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

文本長度限制

字元計算規則

  • 漢字(包括簡/繁體漢字、日文漢字和韓文漢字)按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-v3.5-flash、cosyvoice-v3.5-plus、cosyvoice-v3-flash、cosyvoice-v3-plus和cosyvoice-v2模型,支援識別中小學常見的數學運算式,包括但不限於基礎運算、代數、幾何等內容。

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

SSML標記語言支援說明

當前SSML(Speech Synthesis Markup Language,語音合成標記語言)功能僅適用於cosyvoice-v3.5-flash、cosyvoice-v3.5-plus、cosyvoice-v3-flash、cosyvoice-v3-plus和cosyvoice-v2模型的複刻音色,以及音色列表中標記為支援的系統音色,使用時需滿足以下條件:

快速開始

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

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

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

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

非流式調用

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

image

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

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

重要

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

點擊查看完整樣本

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *
import os

# 新加坡地區和北京地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# 以下為新加坡地區url,若使用北京地區的模型,需將url替換為:wss://dashscope.aliyuncs.com/api-ws/v1/inference
dashscope.base_websocket_api_url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'

# 模型
model = "cosyvoice-v3-flash"
# 音色
voice = "longanyang"

# 執行個體化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中的回呼函數流式擷取。

image

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

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

重要

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

點擊查看完整樣本

# coding=utf-8

import os
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不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# 以下為新加坡地區url,若使用北京地區的模型,需將url替換為:wss://dashscope.aliyuncs.com/api-ws/v1/inference
dashscope.base_websocket_api_url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'

# 模型
model = "cosyvoice-v3-flash"
# 音色
voice = "longanyang"


# 定義回調介面
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())
        # 當任務完成(on_complete 回調觸發)後,才可調用 get_first_package_delay 擷取延遲
        # 首次發送文本時需建立 WebSocket 串連,因此首包延遲會包含串連建立的耗時
        print('[Metric] requestId為:{},首包延遲為:{}毫秒'.format(
            synthesizer.get_last_request_id(),
            synthesizer.get_first_package_delay()))

    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("今天天氣怎麼樣?")

雙向流式調用

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

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

    • 完整語句立即合成

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

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

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

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

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

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

  2. 串流

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

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

    每次調用streaming_call方法發送的文本片段(即text)長度不得超過20000字元,累計發送的文本總長度不得超過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 os
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不同。擷取API Key:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 若沒有配置環境變數,請用百鍊API Key將下行替換為:dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# 以下為新加坡地區url,若使用北京地區的模型,需將url替換為:wss://dashscope.aliyuncs.com/api-ws/v1/inference
dashscope.base_websocket_api_url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'

# 模型
model = "cosyvoice-v3-flash"
# 音色
voice = "longanyang"


# 定義回調介面
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

語音合成模型

不同模型版本需要使用對應版本的音色:

  • cosyvoice-v3.5-flash/cosyvoice-v3.5-plus:無系統音色,僅支援使用複刻音色。

  • cosyvoice-v3-flash/cosyvoice-v3-plus:使用longanyang等音色。

  • cosyvoice-v2:使用longxiaochun_v2等音色。

  • 完整音色列表請參見音色列表

voice

str

語音合成所使用的音色。

支援系統音色和複刻音色:

  • 系統音色:參見音色列表

  • 複刻音色:通過聲音複刻(CosyVoice)功能定製。使用複刻音色時,請確保聲音複刻與語音合成使用同一帳號。詳細操作步驟請參見CosyVoice聲音複刻API

    使用聲音複刻產生的複刻音色時,本請求的model參數值,必須與建立該音色時所用的模型版本(即target_model參數)完全一致。

format

enum

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

若未指定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]。50代表標準音量。音量大小與該值呈線性關係,0為靜音,100為最大音量。

重要

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

  • 1.20.10及以後版本的SDK:volume

  • 1.20.10以前版本的SDK:volumn

speech_rate

float

語速。

預設值:1.0。

取值範圍:[0.5, 2.0]。1.0為標準語速,小於1.0則減慢,大於1.0則加快。

pitch_rate

float

音高。該值作為音高調節的乘數,但其與聽感上的音高變化並非嚴格的線性或對數關係,建議通過測試選擇合適的值。

預設值:1.0。

取值範圍:[0.5, 2.0]。1.0為音色自然音高。大於1.0則音高變高,小於1.0則音高變低。

bit_rate

int

音頻碼率(單位kbps)。音頻格式為opus時,支援通過bit_rate參數調整碼率。

預設值:32。

取值範圍:[6, 510]。

說明

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

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

word_timestamp_enabled

bool

是否開啟字層級時間戳記。

預設值:False。

  • True:開啟。

  • False:關閉。

該功能僅適用於cosyvoice-v3-flash、cosyvoice-v3-plus和cosyvoice-v2模型的複刻音色,以及音色列表中標記為支援的系統音色。

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

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

synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash",
                                voice="longyingjing_v3",
                                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"

model = "cosyvoice-v3-flash"
# 音色
voice = "longyingjing_v3"


# 定義回調介面
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

產生時使用的隨機數種子,使合成的效果產生變化。在模型版本、文本、音色及其他參數均相同的前提下,使用相同的seed可複現相同的合成結果。

預設值0。

取值範圍:[0, 65535]。

language_hints

list[str]

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

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

  • 數字朗讀方式不符合預期,“hello, this is 110”讀成“hello, this is one one zero”而非“hello, this is 么么零”

  • 符號朗讀不準確,“@”讀成“艾特”而非“at”

  • 小語種合成效果差,合成不自然

取值範圍:

  • zh:中文

  • en:英文

  • fr:法語

  • de:德語

  • ja:日語

  • ko:韓語

  • ru:俄語

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

重要

此參數用於指定語音合成的目標語言,該設定與聲音複刻時的樣本音訊語種無關。如果您需要設定複刻任務的源語言,請參見CosyVoice聲音複刻API

instruction

str

設定指令,用於控制方言、情感或角色等合成效果。該功能僅適用於cosyvoice-v3.5-flash、cosyvoice-v3.5-plus和cosyvoice-v3-flash模型的複刻音色,以及音色列表中標記為支援Instruct的系統音色。

長度限制:100字元。

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

使用要求(因模型而異):

  • cosyvoice-v3.5-flash和cosyvoice-v3.5-plus:可以輸入任意指令控制合成效果(如情感、語速等)

    重要

    cosyvoice-v3.5-flash和cosyvoice-v3.5-plus無系統音色,僅支援使用複刻音色。

    指令樣本:

    請用非常激昂且高亢的語氣說話,表現出獲得重大成功後的狂喜與激動。
    語速請保持中等偏慢,語氣要顯得優雅、知性,給人以從容不迫的安心感。
    語氣要充滿哀傷與懷念,帶有輕微的鼻音,彷彿正在訴說一段令人心碎的往事。
    請嘗試用氣聲說話,音量極輕,營造出一種在耳邊親密低語的神秘感。
    語氣要顯得非常急躁且不耐煩,語速加快,句子之間的停頓要盡量縮短。
    請類比一位慈祥、溫和的長輩,語速平穩,聲音中要透出滿滿的關懷與愛意。
    語氣要充滿諷刺和不屑,在關鍵詞上加重讀音,句尾語調略微上揚。
    請用一種極度恐懼且顫抖的聲音說話。
    語氣要像專業的新聞播音員一樣,冷靜、客觀且字正腔圓,情緒保持中立。
    語氣要顯得活潑俏皮,帶著明顯的笑意,讓聲音聽起來充滿朝氣與陽光。
  • cosyvoice-v3-flash:需遵照如下要求

    • 複刻音色:可使用任意自然語言控制語音合成效果。

      指令樣本:

      請用廣東話表達。(支援的方言:廣東話、東北話、甘肅話、貴州話、河南話、湖北話、江西話、閩南話、寧夏話、山西話、陝西話、山東話、上海話、四川話、天津話、雲南話。)
      請儘可能非常大聲地說一句話。
      請用儘可能慢地語速說一句話。
      請用儘可能快地語速說一句話。
      請非常輕聲地說一句話。
      你可以慢一點說嗎
      你可以非常快一點說嗎
      你可以非常慢一點說嗎
      你可以快一點說嗎
      請非常生氣地說一句話。
      請非常開心地說一句話。
      請非常恐懼地說一句話。
      請非常傷心地說一句話。
      請非常驚訝地說一句話。
      請儘可能表現出堅定的感覺。
      請儘可能表現出憤怒的感覺。
      請嘗試一下親和的語調。
      請用冷酷的語調講話。
      請用威嚴的語調講話。
      我想體驗一下自然的語氣。
      我想看看你如何表達威脅。
      我想看看你怎麼表現智慧。
      我想看看你怎麼表現誘惑。
      我想聽聽用活潑的方式說話。
      我想聽聽你用激昂的感覺說話。
      我想聽聽用沉穩的方式說話的樣子。
      我想聽聽你用自信的感覺說話。
      你能用興奮的感覺和我交流嗎?
      你能否展示狂傲的情緒表達?
      你能展現一下優雅的情緒嗎?
      你可以用幸福的方式回答問題嗎?
      你可以做一個溫柔的情感示範嗎?
      能用冷靜的語調和我談談嗎?
      能用深沉的方法回答我嗎?
      能用粗獷的情緒態度和我對話嗎?
      用陰森的聲音告訴我這個答案。
      用堅韌的聲音告訴我這個答案。
      用自然親切的閑聊風格敘述。
      用廣播劇部落客的語氣講話。
    • 系統音色:指令必須使用固定格式和內容,詳情請參見音色列表

enable_aigc_tag

bool

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

預設值:False。

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

說明

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

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

aigc_propagator

str

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

預設值:阿里雲UID。

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

說明

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

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

aigc_propagate_id

str

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

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

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

說明

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

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

hot_fix

dict

文本熱修複配置,用於自訂指定詞語的發音或對待合成文本進行替換。僅cosyvoice-v3-flash複刻音色支援該功能。

參數介紹:

  • pronunciation:自訂發音。指定詞語的拼音標註,用於糾正預設發音不準確的情況。

  • replace:文本替換。在語音合成前將指定詞語替換為目標文本,替換後的文本將作為實際合成內容。

樣本:

synthesizer = SpeechSynthesizer(
    model="cosyvoice-v3-flash",
    voice="your_voice", # 替換成cosyvoice-v3-flash複刻音色
    hot_fix={
        "pronunciation": [{"天氣": "tian1 qi4"}],
        "replace": [{"今天": "金天"}]
    }
)

enable_markdown_filter

bool

是否啟用 Markdown 過濾。啟用該功能後,系統在合成語音前自動過濾輸入文本中的 Markdown 標記符號,避免將其朗讀為文字內容。僅cosyvoice-v3-flash複刻音色支援該功能。

預設值:False。

取值範圍:

  • True:啟用Markdown過濾

  • False:禁用Markdown過濾

說明

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

synthesizer = SpeechSynthesizer(
    model="cosyvoice-v3-flash",
    voice="your_voice", # 替換成cosyvoice-v3-flash複刻音色
    additional_params={"enable_markdown_filter": True}
)

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)

首包延遲

擷取當前任務的首包延遲,任務結束後使用。首包延遲是開始發送文本和接收第一個音頻包之間的時間,單位為毫秒。

影響首包延遲的因素:

  • WebSocket串連建立耗時(首次調用)

  • 音色載入時間(不同音色載入時間不同)

  • 服務承載量(高峰期可能出現排隊等待)

  • 網路延遲

典型延遲範圍:

  • 複用串連且音色已載入:500ms左右

  • 首次串連或切換音色:可能達到1500~2000ms

若首包延遲持續過高(>2000ms),建議:

  1. 使用高並發情境下的串連池功能提前建立串連

  2. 檢查網路連接品質

  3. 避免在高峰時段調用

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. 確保限制與約束正確

  2. 安裝最新版本 DashScope SDK

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

  4. 確保待合成文本為純文字格式且符合格式要求,詳情請參見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:合成的語音發音錯誤如何處理?

請使用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