# 语音合成CosyVoice Python SDK https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#915a935d871ak ```python dashscope.api_key = "sk-6fecb52bb96d4492bb7e58213eeeb00f" ``` ### **流式调用** 在同一个语音合成任务中分多次提交文本，并通过回调的方式实时获取合成结果。 **说明** - 流式输入时可多次调用`streaming_call`按顺序提交文本片段。服务端接收文本片段后自动进行分句： - 完整语句立即合成 - 不完整语句缓存至完整后合成 调用 `streaming_complete` 时，服务端会强制合成所有已接收但未处理的文本片段（包括未完成的句子）。 - 发送文本片段的间隔不得超过23秒，否则触发“request timeout after 23 seconds”异常。 若无待发送文本，需及时调用 `streaming_complete`结束任务。 > 服务端强制设定23秒超时机制，客户端无法修改该配置。 ![image](https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/0165103671/CAEQVRiBgMDb7PahrBkiIDVkNjEwOTMxYjEwOTRmOWFhMmI1OTRiY2Q3ZDgzZmE54709861_20241015153444.149.svg) 1. 实例化SpeechSynthesizer类 实例化[SpeechSynthesizer类](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#d6bc1f133f871)绑定[请求参数](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#2fe363ace1l4k)和[回调接口（ResultCallback）](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#85d698b9f9g8s)。 2. 流式传输 多次调用[SpeechSynthesizer类](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#d6bc1f133f871)的`streaming_call`方法分片提交待合成文本，将待合成文本分段发送至服务端。 在发送文本的过程中，服务端会通过[回调接口（ResultCallback）](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#85d698b9f9g8s)的`on_data`方法，将合成结果实时返回给客户端。 每次调用`streaming_call`方法发送的文本片段（即`text`）长度不得超过2000字符，累计发送的文本总长度不得超过20万字符。 3. 结束处理 调用[SpeechSynthesizer类](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#d6bc1f133f871)的`streaming_complete`方法结束语音合成。 该方法会阻塞当前线程，直到[回调接口（ResultCallback）](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#85d698b9f9g8s)的`on_complete`或者`on_error`回调触发后才会释放线程阻塞。 请务必确保调用该方法，否则可能会导致结尾部分的文本无法成功转换为语音。 ~~~python # 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类](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#d6bc1f133f871)的构造方法进行设置。 | | | | | | | ---- | ---- | ---- | ---- | ---- | | | | | | | | **参数** | **类型** | **默认值** | **是否必须** | **说明** | | ---------------------- | -------------- | ---------- | ------------ | ------------------------------------------------------------ | | model | str | - | 是 | 指定模型。不同版本的模型编码方式一致，但使用时须确保模型（`model`）与音色（`voice`）匹配：每个版本的模型只能使用本版本的默认音色或专属音色。 | | voice | str | - | 是 | 指定语音合成所使用的音色。支持默认音色和专属音色：**默认音色**：参见**音色列表**章节。**专属音色**：通过[声音复刻](https://help.aliyun.com/zh/model-studio/voice-replica-1/)功能定制。使用复刻音色时，请确保声音复刻与语音合成使用同一账号。详细操作步骤请参见[CosyVoice声音复刻API](https://help.aliyun.com/zh/model-studio/cosyvoice-clone-api#da30eeebc4uwk)。**⚠️ 使用声音复刻系列模型合成语音时，仅能使用该模型复刻生成的专属音色，不能使用默认音色。****⚠️ 使用专属音色合成语音时，语音合成模型（**`**model**`**）必须与声音复刻模型（**`**target_model**`**）相同。** | | format | enum | 因音色而异 | 否 | 指定音频编码格式及采样率。若未指定`format`，则合成音频采样率为22.05kHz，格式为mp3。**说明**默认采样率代表当前音色的最佳采样率，缺省条件下默认按照该采样率输出，同时支持降采样或升采样。可指定的音频编码格式及采样率如下：所有模型均支持的音频编码格式及采样率：AudioFormat.WAV_8000HZ_MONO_16BIT，代表音频格式为wav，采样率为8kHzAudioFormat.WAV_16000HZ_MONO_16BIT，代表音频格式为wav，采样率为16kHzAudioFormat.WAV_22050HZ_MONO_16BIT，代表音频格式为wav，采样率为22.05kHzAudioFormat.WAV_24000HZ_MONO_16BIT，代表音频格式为wav，采样率为24kHzAudioFormat.WAV_44100HZ_MONO_16BIT，代表音频格式为wav，采样率为44.1kHzAudioFormat.WAV_48000HZ_MONO_16BIT，代表音频格式为wav，采样率为48kHzAudioFormat.MP3_8000HZ_MONO_128KBPS，代表音频格式为mp3，采样率为8kHzAudioFormat.MP3_16000HZ_MONO_128KBPS，代表音频格式为mp3，采样率为16kHzAudioFormat.MP3_22050HZ_MONO_256KBPS，代表音频格式为mp3，采样率为22.05kHzAudioFormat.MP3_24000HZ_MONO_256KBPS，代表音频格式为mp3，采样率为24kHzAudioFormat.MP3_44100HZ_MONO_256KBPS，代表音频格式为mp3，采样率为44.1kHzAudioFormat.MP3_48000HZ_MONO_256KBPS，代表音频格式为mp3，采样率为48kHzAudioFormat.PCM_8000HZ_MONO_16BIT，代表音频格式为pcm，采样率为8kHzAudioFormat.PCM_16000HZ_MONO_16BIT，代表音频格式为pcm，采样率为16kHzAudioFormat.PCM_22050HZ_MONO_16BIT，代表音频格式为pcm，采样率为22.05kHzAudioFormat.PCM_24000HZ_MONO_16BIT，代表音频格式为pcm，采样率为24kHzAudioFormat.PCM_44100HZ_MONO_16BIT，代表音频格式为pcm，采样率为44.1kHzAudioFormat.PCM_48000HZ_MONO_16BIT，代表音频格式为pcm，采样率为48kHz除`cosyvoice-v1`外，其他模型支持的音频编码格式及采样率：音频格式为opus时，支持通过`bit_rate`参数调整码率。仅对1.24.0及之后版本的DashScope适用。AudioFormat.OGG_OPUS_8KHZ_MONO_32KBPS，代表音频格式为opus，采样率为8kHz，码率为32kbpsAudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS，代表音频格式为opus，采样率为16kHz，码率为16kbpsAudioFormat.OGG_OPUS_16KHZ_MONO_32KBPS，代表音频格式为opus，采样率为16kHz，码率为32kbpsAudioFormat.OGG_OPUS_16KHZ_MONO_64KBPS，代表音频格式为opus，采样率为16kHz，码率为64kbpsAudioFormat.OGG_OPUS_24KHZ_MONO_16KBPS，代表音频格式为opus，采样率为24kHz，码率为16kbpsAudioFormat.OGG_OPUS_24KHZ_MONO_32KBPS，代表音频格式为opus，采样率为24kHz，码率为32kbpsAudioFormat.OGG_OPUS_24KHZ_MONO_64KBPS，代表音频格式为opus，采样率为24kHz，码率为64kbpsAudioFormat.OGG_OPUS_48KHZ_MONO_16KBPS，代表音频格式为opus，采样率为48kHz，码率为16kbpsAudioFormat.OGG_OPUS_48KHZ_MONO_32KBPS，代表音频格式为opus，采样率为48kHz，码率为32kbpsAudioFormat.OGG_OPUS_48KHZ_MONO_64KBPS，代表音频格式为opus，采样率为48kHz，码率为64kbps | | volume | int | 50 | 否 | 合成音频的音量，取值范围：0~100。**重要**该字段在不同版本的DashScope SDK中有所不同：1.20.10及以后版本的SDK：volume1.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 | 否 | 指定音频的[码率](https://opus-codec.org/)，取值范围：6~510kbps。码率越大，音质越好，音频文件体积越大。仅在音频格式（`format`）为opus时可用。`cosyvoice-v1`模型不支持该参数。**说明**`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})`**点击查看完整示例代码** | | seed | int | 0 | 否 | 生成时使用的随机数种子，使合成的效果产生变化。默认值0。取值范围：0~65535。cosyvoice-v1不支持该功能。 | | language_hints | list[str] | - | 否 | 合成文本语言提示，可选值为 `zh`（中文）或 `en`（英文），列表中仅第一个语言生效。仅cosyvoice-v3、cosyvoice-v3-plus支持该功能。此设置会影响阿拉伯数字等内容的读法。例如，当合成“123”时，若设置为`zh`，则读作“一百二十三”；而`en`则会读作“one hundred and twenty-three”。如果不设置，系统会根据文本内容自动判断并应用相应的合成规则。 | | instruction | String | - | 否 | 设置提示词。仅cosyvoice-v3、cosyvoice-v3-plus支持该功能。目前仅支持设置情感。格式：“`你说话的情感是<情感值>。`”（注意，结尾一定不要遗漏句号，使用时将“`<情感值>`”替换为具体的情感值，例如替换为`neutral`）。示例：“`你说话的情感是neutral。`”支持的情感值：`neutral`、`fearful`、`angry`、`sad`、`surprised`、`happy`、`disgusted`。 | | callback | ResultCallback | - | 否 | [回调接口（ResultCallback）](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#85d698b9f9g8s). | ## **关键接口** ### `SpeechSynthesizer`类 `SpeechSynthesizer`通过“`from dashscope.audio.tts_v2 import *`”方式引入，提供语音合成的关键接口。 | | | | | | ---- | ---- | ---- | ---- | | | | | | | **方法** | **参数** | **返回值** | **描述** | | ------------------------------------------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------ | | `def call(self, text: str, timeout_millis=None)` | `text`：待合成文本`timeout_millis`：阻塞线程的超时时间，单位为毫秒，不设置或值为0时不生效 | 没有指定`ResultCallback`时返回二进制音频数据，否则返回None | 将整段文本（无论是纯文本还是包含[SSML](https://help.aliyun.com/zh/model-studio/introduction-to-cosyvoice-ssml-markup-language)的文本）转换为语音。在创建`SpeechSynthesizer`实例时，存在以下两种情况：没有指定`ResultCallback`：`call`方法会阻塞当前线程直到语音合成完成并返回二进制音频数据。使用方法请参见[同步调用](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#8341058094tc3)。指定了`ResultCallback`：`call`方法会立刻返回None，并通过[回调接口（ResultCallback）](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#85d698b9f9g8s)的`on_data`方法返回语音合成的结果。使用方法请参见[异步调用](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#cc2a504f344s2)。**重要**每次调用`call`方法前，需要重新初始化`SpeechSynthesizer`实例。 | | `def streaming_call(self, text: str)` | `text`：待合成文本片段 | 无 | 流式发送待合成文本（不支持包含SSML的文本）。您可以多次调用该接口，将待合成文本分多次发送给服务端。合成结果通过[回调接口（ResultCallback）](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#85d698b9f9g8s)的`on_data`方法获取。使用方法请参见[流式调用](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#ba023aacfbr84)。 | | `def streaming_complete(self, complete_timeout_millis=600000)` | `complete_timeout_millis`：等待时间，单位为毫秒 | 无 | 结束流式语音合成。该方法阻塞当前线程N毫秒（具体时长由`complete_timeout_millis`决定），直到任务结束。如果`completeTimeoutMillis`设置为0，则无限期等待。默认情况下，如果等待时间超过10分钟，则停止等待。使用方法请参见[流式调用](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#ba023aacfbr84)。**重要**在[流式调用](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#ba023aacfbr84)时，请务必确保调用该方法，否则可能会出现合成语音缺失的问题。 | | `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`） [异步调用](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#cc2a504f344s2)或[流式调用](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#ba023aacfbr84)时，服务端会通过回调的方式，将关键流程信息和数据返回给客户端。您需要实现回调方法，处理服务端返回的信息或者数据。 通过“`from dashscope.audio.tts_v2 import *`”方式引入。 点击查看示例 | | | | | | ---- | ---- | ---- | ---- | | | | | | | **方法** | **参数** | **返回值** | **描述** | | ------------------------------------------- | ---------------------------------- | ---------- | ------------------------------------------------------------ | | `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` | 无 | 无 | 当服务已经关闭连接后被回调。 | ## **响应结果** 服务器返回二进制音频数据： - [同步调用](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#8341058094tc3)：对[SpeechSynthesizer类](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#d6bc1f133f871)的`call`方法返回的二进制音频数据进行处理。 - [异步调用](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#cc2a504f344s2)或[流式调用](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#ba023aacfbr84)：对[回调接口（ResultCallback）](https://help.aliyun.com/zh/model-studio/cosyvoice-python-sdk#85d698b9f9g8s)的`on_data`方法的参数（bytes类型数据）进行处理。 ## **错误码** 如遇报错问题，请参见[错误信息](https://help.aliyun.com/zh/model-studio/error-code)进行排查。 若问题仍未解决，请加入[开发者群](https://github.com/aliyun/alibabacloud-bailian-speech-demo)反馈遇到的问题，并提供Request ID，以便进一步排查问题。 ## **音色列表** 当前默认支持的音色如下表所示。若您需要更加个性化的音色，可通过声音复刻功能免费定制专属音色，详情请参见[使用复刻的音色进行语音合成](https://help.aliyun.com/zh/model-studio/cosyvoice-clone-api#b6d3449fb336v)。 进行语音合成时，`model`参数必须与所选音色对应，否则调用将失败。 待合成文本（text）应使用与所选音色语种一致的语言，否则可能出现发音错误或不自然 cosyvoice-v3 cosyvoice-v2 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 | 语音助手、客服催收、新闻播报、导航播报 | 中文普通话 |