语音合成CosyVoice Python SDK

用户指南：关于模型介绍和选型建议请参见语音合成-CosyVoice/Sambert。

在线体验：仅cosyvoice-v1支持在线体验。

• 已开通服务并获取API Key。请配置API Key到环境变量，而非硬编码在代码中，防范因代码泄露导致的安全风险。

  说明

  当您需要为第三方应用或用户提供临时访问权限，或者希望严格控制敏感数据访问、删除等高风险操作时，建议使用临时鉴权Token。

  与长期有效的 API Key 相比，临时鉴权 Token 具备时效性短（60秒）、安全性高的特点，适用于临时调用场景，能有效降低API Key泄露的风险。

  使用方式：在代码中，将原本用于鉴权的 API Key 替换为获取到的临时鉴权 Token 即可。

• 安装最新版DashScope SDK。

文本长度限制

• 非流式调用（同步调用或异步调用）：单次发送文本长度不得超过 2000 字符。

• 流式调用：单次发送文本长度不得超过 2000 字符，且累计发送文本总长度不得超过 20 万字符。

SSML标记语言支持说明

当前SSML（Speech Synthesis Markup Language，语音合成标记语言）功能仅适用于cosyvoice-v2模型的部分音色（请查看音色列表确认是否支持SSML），使用时需满足以下条件：

• 使用DashScope SDK 1.23.4 或更高版本

• 仅支持同步调用和异步调用（即SpeechSynthesizer类的call方法），不支持流式调用（即SpeechSynthesizer类的streaming_call方法）

• 使用方法与普通语音合成一致：将包含SSML的文本传入SpeechSynthesizer类的call方法即可

同步调用

提交单个语音合成任务，无需调用回调函数，进行语音合成（无流式输出中间结果），最终一次性获取完整结果。

实例化SpeechSynthesizer类绑定请求参数，调用call方法进行合成并获取二进制音频数据。

发送的文本长度不得超过2000字符（详情请参见SpeechSynthesizer类的call方法）。

# 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方法）。

# 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()))

流式调用

在同一个语音合成任务中分多次提交文本，并通过回调的方式实时获取合成结果。

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类

SpeechSynthesizer通过“from dashscope.audio.tts_v2 import *”方式引入，提供语音合成的关键接口。

def call(self, text: str, timeout_millis=None)

def streaming_call(self, text: str)

def streaming_complete(self, complete_timeout_millis=600000)

def get_last_request_id(self)

def get_first_package_delay(self)

def get_response(self)

回调接口（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

def on_complete(self) -> None

def on_error(self, message) -> None

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

def on_close(self) -> None

如遇报错问题，请参见错误信息进行排查。

若问题仍未解决，请加入开发者群反馈遇到的问题，并提供Request ID，以便进一步排查问题。

当前默认支持的音色如下表所示。若您需要更加个性化的音色，可通过声音复刻功能免费定制专属音色，详情请参见使用复刻的音色进行语音合成。

• cosyvoice-v2音色列表

  重要

  以下为cosyvoice-v2音色列表，使用时必须将请求参数model设置为cosyvoice-v2，否则将调用失败。

  cosyvoice-v1音色列表请参见cosyvoice-v1音色列表

  适用场景	音色	音色特质	音频试听（右键保存音频）	voice参数	语言	SSML	权限要求
  童声（标杆音色）	龙火火	桀骜不驯男童		longhuohuo	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  	龙呼呼	天真烂漫女童		longhuhu	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  方言（标杆音色）	龙川叔	油腻搞笑叔		longchuanshu	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  消费电子-教育培训	龙安培	青少年教师女		longanpei	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  消费电子-儿童陪伴	龙汪汪	台湾少年音		longwangwang	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  	龙泡泡	飞天泡泡音		longpaopao	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  消费电子-儿童有声书	龙闪闪	戏剧化童声		longshanshan	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  	龙牛牛	阳光男童声		longniuniu	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  短视频配音	龙黛玉	娇率才女音		longdaiyu	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  	龙高僧	得道高僧音		longgaoseng	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  客服	龙应沐	优雅知性女		longyingmu	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  	龙应询	年轻青涩男		longyingxun	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  	龙应催	严肃催收男		longyingcui	中、英	✅	✅可直接使用
  	龙应答	开朗高音女		longyingda	中、英	✅	✅可直接使用
  	龙应静	低调冷静女		longyingjing	中、英	✅	✅可直接使用
  	龙应严	义正严辞女		longyingyan	中、英	✅	✅可直接使用
  	龙应甜	温柔甜美女		longyingtian	中、英	✅	✅可直接使用
  	龙应冰	尖锐强势女		longyingbing	中、英	✅	✅可直接使用
  	龙应桃	温柔淡定女		longyingtao	中、英	✅	✅可直接使用
  	龙应聆	温和共情女		longyingling	中、英	✅	✅可直接使用
  语音助手	YUMI	正经青年女		longyumi_v2	中、英	✅	✅可直接使用
  	龙小淳	知性积极女		longxiaochun_v2	中、英	✅	✅可直接使用
  	龙小夏	沉稳权威女		longxiaoxia_v2	中、英	✅	✅可直接使用
  直播带货	龙安燃	活泼质感女		longanran	中、英	✅	✅可直接使用
  	龙安宣	经典直播女		longanxuan	中、英	✅	✅可直接使用
  	龙安冲	激情推销男		longanchong	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  	龙安萍	高亢直播女		longanping	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  有声书	龙白芷	睿气旁白女		longbaizhi	中、英	✅	⚠️ 若有语音服务业务对接人，请直接联系其申请开通；否则请提交工单申请
  	龙三叔	沉稳质感男		longsanshu	中、英	✅	✅可直接使用
  	龙修	博才说书男		longxiu_v2	中、英	✅	✅可直接使用
  	龙妙	抑扬顿挫女		longmiao_v2	中、英	✅	✅可直接使用
  	龙悦	温暖磁性女		longyue_v2	中、英	✅	✅可直接使用
  	龙楠	睿智青年男		longnan_v2	中、英	✅	✅可直接使用
  	龙媛	温暖治愈女		longyuan_v2	中、英	✅	✅可直接使用
  社交陪伴	龙安柔	温柔闺蜜女		longanrou	中、英	✅	✅可直接使用
  	龙嫱	浪漫风情女		longqiang_v2	中、英	✅	✅可直接使用
  	龙寒	温暖痴情男		longhan_v2	中、英	✅	✅可直接使用
  	龙星	温婉邻家女		longxing_v2	中、英	✅	✅可直接使用
  	龙华	元气甜美女		longhua_v2	中、英	✅	✅可直接使用
  	龙婉	积极知性女		longwan_v2	中、英	✅	✅可直接使用
  	龙橙	智慧青年男		longcheng_v2	中、英	✅	✅可直接使用
  	龙菲菲	甜美娇气女		longfeifei_v2	中、英	✅	✅可直接使用
  	龙小诚	磁性低音男		longxiaocheng_v2	中、英	✅	✅可直接使用
  	龙哲	呆板大暖男		longzhe_v2	中、英	✅	✅可直接使用
  	龙颜	温暖春风女		longyan_v2	中、英	✅	✅可直接使用
  	龙天	磁性理智男		longtian_v2	中、英	✅	✅可直接使用
  	龙泽	温暖元气男		longze_v2	中、英	✅	✅可直接使用
  	龙邵	积极向上男		longshao_v2	中、英	✅	✅可直接使用
  	龙浩	多情忧郁男		longhao_v2	中、英	✅	✅可直接使用
  	龙深	实力歌手男		kabuleshen_v2	中、英	✅	✅可直接使用
  童声	龙杰力豆	阳光顽皮男		longjielidou_v2	中、英	✅	✅可直接使用
  	龙铃	稚气呆板女		longling_v2	中、英	✅	✅可直接使用
  	龙可	懵懂乖乖女		longke_v2	中、英	✅	✅可直接使用
  	龙仙	豪放可爱女		longxian_v2	中、英	✅	✅可直接使用
  方言	龙老铁	东北直率男		longlaotie_v2	中（东北）、英	✅	✅可直接使用
  	龙嘉怡	知性粤语女		longjiayi_v2	中（粤语）、英	✅	✅可直接使用
  	龙桃	积极粤语女		longtao_v2	中（粤语）、英	✅	✅可直接使用
  诗词朗诵	龙飞	热血磁性男		longfei_v2	中、英	✅	✅可直接使用
  	李白	古代诗仙男		libai_v2	中、英	✅	✅可直接使用
  	龙津	优雅温润男		longjin_v2	中、英	✅	✅可直接使用
  新闻播报	龙书	沉稳青年男		longshu_v2	中、英	✅	✅可直接使用
  	Bella2.0	精准干练女		loongbella_v2	中、英	✅	✅可直接使用
  	龙硕	博才干练男		longshuo_v2	中、英	✅	✅可直接使用
  	龙小白	沉稳播报女		longxiaobai_v2	中、英	✅	✅可直接使用
  	龙婧	典型播音女		longjing_v2	中、英	✅	✅可直接使用
  	loongstella	飒爽利落女		loongstella_v2	中、英	✅	✅可直接使用
  出海营销	loongeva	知性英文女		loongeva_v2	英式英文	❌	✅可直接使用
  	loongbrian	沉稳英文男		loongbrian_v2	英式英文	❌	✅可直接使用
  	loongluna	英式英文女		loongluna_v2	英式英文	❌	✅可直接使用
  	loongluca	英式英文男		loongluca_v2	英式英文	❌	✅可直接使用
  	loongemily	英式英文女		loongemily_v2	英式英文	❌	✅可直接使用
  	loongeric	英式英文男		loongeric_v2	英式英文	❌	✅可直接使用
  	loongabby	美式英文女		loongabby_v2	美式英文	❌	✅可直接使用
  	loongannie	美式英文女		loongannie_v2	美式英文	❌	✅可直接使用
  	loongandy	美式英文男		loongandy_v2	美式英文	❌	✅可直接使用
  	loongava	美式英文女		loongava_v2	美式英文	❌	✅可直接使用
  	loongbeth	美式英文女		loongbeth_v2	美式英文	❌	✅可直接使用
  	loongbetty	美式英文女		loongbetty_v2	美式英文	❌	✅可直接使用
  	loongcindy	美式英文女		loongcindy_v2	美式英文	❌	✅可直接使用
  	loongcally	美式英文女		loongcally_v2	美式英文	❌	✅可直接使用
  	loongdavid	美式英文男		loongdavid_v2	美式英文	❌	✅可直接使用
  	loongdonna	美式英文女		loongdonna_v2	美式英文	❌	✅可直接使用
  	loongkyong	韩语女		loongkyong_v2	韩语	❌	✅可直接使用
  	loongtomoka	日语女		loongtomoka_v2	日语	❌	✅可直接使用
  	loongtomoya	日语男		loongtomoya_v2	日语	❌	✅可直接使用

• cosyvoice-v1音色列表

  点击查看cosyvoice-v1音色列表

  相较于cosyvoice-v1，cosyvoice-v2效果更好，音色更丰富，且cosyvoice-v2大部分音色支持SSML功能，建议优先使用cosyvoice-v2音色体验更好的效果。

  重要

  • 使用v1音色时，必须将请求参数model设置为cosyvoice-v1，否则将调用失败。

  • 如果当前音色在“语言”列中未明确标注支持的口音，则表明该音色不区分具体口音。

  音色	音频试听（右键保存音频）	voice参数	适用场景	语言
  龙婉		longwan	语音助手、 导航播报、 聊天数字人	中文普通话
  龙橙		longcheng	语音助手、 导航播报、 聊天数字人	中文普通话
  龙华		longhua	语音助手、 导航播报、 聊天数字人	中文普通话
  龙小淳		longxiaochun	语音助手、 导航播报、 聊天数字人	中文普通话+英文
  龙小夏		longxiaoxia	语音助手、聊天数字人	中文普通话
  龙小诚		longxiaocheng	语音助手、导航播报、聊天数字人	中文普通话+英文
  龙小白		longxiaobai	聊天数字人、有声书、语音助手	中文普通话
  龙老铁		longlaotie	新闻播报、有声书、语音助手、直播带货、导航播报	中文东北口音
  龙书		longshu	有声书、语音助手、导航播报、新闻播报、智能客服	中文普通话
  龙硕		longshuo	语音助手、导航播报、新闻播报、客服催收	中文普通话
  龙婧		longjing	语音助手、导航播报、新闻播报、客服催收	中文普通话
  龙妙		longmiao	客服催收、导航播报、有声书、语音助手	中文普通话
  龙悦		longyue	语音助手、诗词朗诵、有声书朗读、导航播报、新闻播报、客服催收	中文普通话
  龙媛		longyuan	有声书、语音助手、聊天数字人	中文普通话
  龙飞		longfei	会议播报、新闻播报、有声书	中文普通话
  龙杰力豆		longjielidou	新闻播报、有声书、聊天助手	中文普通话+英文
  龙彤		longtong	有声书、导航播报、聊天数字人	中文普通话
  龙祥		longxiang	新闻播报、有声书、导航播报	中文普通话
  Stella		loongstella	语音助手、直播带货、导航播报、客服催收、有声书	中文普通话+英文
  Bella		loongbella	语音助手、客服催收、新闻播报、导航播报	中文普通话

功能特性/计量计费/限流

故障排查

如遇代码报错问题，请根据错误码中的信息进行排查。

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

权限与认证

更多问题

请参见GitHub QA。