语音合成CosyVoice Python API

更新时间:2025-04-14 09:49:57

本文介绍语音合成CosyVoice Python API的使用。

前提条件

快速开始

SpeechSynthesizer提供了语音合成的关键接口,支持以下几种调用方式:

  • 同步调用:提交文本后,服务端立即处理并返回完整的语音合成结果。整个过程是阻塞式的,客户端需要等待服务端完成处理后才能继续下一步操作。适合短文本合成场景。

  • 异步调用:将文本一次发送至服务端并实时接收语音合成结果,不允许将文本分段发送。适用于对实时性要求高的短文本语音合成场景。

  • 流式调用:将文本逐步发送到服务端并实时接收语音合成结果,允许将长文本分段发送,服务端在接收到部分文本后便立即开始处理。适合实时性要求高的场景。

同步调用

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

image

实例化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-v1"
voice = "longxiaochun"

synthesizer = SpeechSynthesizer(model=model, voice=voice)
audio = synthesizer.call("今天天气怎么样?")
print('[Metric] requestId: {}, first package delay ms: {}'.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方法实时获取合成结果。

点击查看完整示例

# 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-v1"
voice = "longxiaochun"


class Callback(ResultCallback):
    _player = None
    _stream = None

    def on_open(self):
        self.file = open("output.mp3", "wb")
        print(get_timestamp() + " websocket is open.")

    def on_complete(self):
        print(get_timestamp() + " speech synthesis task complete successfully.")

    def on_error(self, message: str):
        print(f"speech synthesis task failed, {message}")

    def on_close(self):
        print(get_timestamp() + " websocket is closed.")
        self.file.close()

    def on_event(self, message):
        pass

    def on_data(self, data: bytes) -> None:
        print(get_timestamp() + " audio result length: " + str(len(data)))
        self.file.write(data)


callback = Callback()

synthesizer = SpeechSynthesizer(
    model=model,
    voice=voice,
    callback=callback,
)

synthesizer.call("今天天气怎么样?")
print('[Metric] requestId: {}, first package delay ms: {}'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

流式调用

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

说明
  • 流式输入时可多次调用streaming_call按顺序提交文本片段。服务端接收文本片段后自动进行分句:

    • 完整语句立即合成

    • 不完整语句缓存至完整后合成

    调用 streaming_complete 时,服务端会强制合成所有已接收但未处理的文本片段(包括未完成的句子)。

  • 发送文本片段的间隔不得超过23秒,否则触发“request timeout after 23 seconds”异常。

    若无待发送文本,需及时调用 streaming_complete结束任务。

    服务端强制设定23秒超时机制,客户端无法修改该配置。
image
  1. 实例化SpeechSynthesizer

    实例化SpeechSynthesizer绑定请求参数回调接口(ResultCallback)

  2. 流式传输

    循环调用SpeechSynthesizerstreaming_call方法分片提交待合成文本,将待合成文本分段发送至服务端。

    在发送文本的过程中,服务端会通过回调接口(ResultCallback)on_data方法,将合成结果实时返回给客户端。

  3. 结束处理

    调用SpeechSynthesizerstreaming_complete方法结束语音合成。

    该方法会阻塞当前线程,直到回调接口(ResultCallback)on_complete或者on_error回调触发后才会释放线程阻塞。

点击查看完整示例

# coding=utf-8
#
# Installation instructions for pyaudio:
# APPLE Mac OS X
#   brew install portaudio
#   pip install pyaudio
# Debian/Ubuntu
#   sudo apt-get install python-pyaudio python3-pyaudio
#   or
#   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-v1"
voice = "longxiaochun"


class Callback(ResultCallback):
    _player = None
    _stream = None

    def on_open(self):
        print("websocket is open.")
        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() + " speech synthesis task complete successfully.")

    def on_error(self, message: str):
        print(f"speech synthesis task failed, {message}")

    def on_close(self):
        print(get_timestamp() + " websocket is closed.")
        # 停止播放器
        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() + " audio result length: " + str(len(data)))
        self._stream.write(data)


callback = Callback()

test_text = [
    "流式文本语音合成SDK,",
    "可以将输入的文本",
    "合成为语音二进制数据,",
    "相比于非流式语音合成,",
    "流式合成的优势在于实时性",
    "更强。用户在输入文本的同时",
    "可以听到接近同步的语音输出,",
    "极大地提升了交互体验,",
    "减少了用户等待时间。",
    "适用于调用大规模",
    "语言模型(LLM),以",
    "流式输入文本的方式",
    "进行语音合成的场景。",
]

synthesizer = SpeechSynthesizer(
    model=model,
    voice=voice,
    format=AudioFormat.PCM_22050HZ_MONO_16BIT,  
    callback=callback,
)


for text in test_text:
    synthesizer.streaming_call(text)
    time.sleep(0.1)
synthesizer.streaming_complete()

print('[Metric] requestId: {}, first package delay ms: {}'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

请求参数

请求参数通过SpeechSynthesizer的构造方法进行设置。

参数

类型

默认值

是否必须

说明

参数

类型

默认值

是否必须

说明

model

str

-

指定模型,支持cosyvoice-v1cosyvoice-v2

voice

str

-

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

支持如下两种音色:

  • 默认音色(参见音色列表)。

  • 通过声音复刻功能定制的专属音色。使用声音复刻音色时(请确保声音复刻与语音合成使用同一账号),需将voice参数设置为复刻音色的ID,完整操作流程请参见使用复刻的音色进行语音合成。目前,仅cosyvoice-v1模型支持声音复刻功能。

format

enum

因音色而异

指定音频编码格式及采样率。

若未指定format,系统将根据voice参数自动选择该音色的推荐格式(如龙小淳默认使用MP3_22050HZ_MONO_256KBPS),详情请参见音色列表

可指定的音频编码格式及采样率如下:

  • 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

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。

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

将整段文本转换为语音。

  • 如果在创建SpeechSynthesizer实例时,没有指定ResultCallback,则call方法会阻塞当前线程直到语音合成完成并返回二进制音频数据。使用方法请参见同步调用

  • 如果指定ResultCallbackcall方法会立刻返回None,并通过回调接口(ResultCallback)on_data方法返回语音合成的结果。使用方法请参见异步调用

def streaming_call(self, text: str)

text:待合成文本片段

流式发送待合成文本。

您可以多次调用该接口,将待合成文本分多次发送给服务端。合成结果通过回调接口(ResultCallback)on_data方法获取。

必须在所有streaming_call调用完成后执行streaming_complete结束任务。

使用方法请参见流式调用

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)

首包延迟

获取首包延迟。

首包延迟是开始发送文本和接收第一个音频包之间的时间,单位为毫秒。在任务完成后使用。

def get_response(self)

最后一次报文

获取最后一次报文(为JSON格式的数据),可以用于获取task-failed报错。

回调接口(ResultCallback

异步调用流式调用时,服务端会通过回调的方式,将关键流程信息和数据返回给客户端。您需要实现回调方法,处理服务端返回的信息或者数据。

点击查看示例

class Callback(ResultCallback):
    def on_open(self) -> None:
        print('连接成功')

    def on_event(self, message) -> None:
        # 实现接收合成结果的逻辑
    
    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:服务端返回的信息

当服务有回复时会被回调。

def on_complete(self) -> None

当所有合成数据全部返回后被回调。

def on_error(self, message) -> None

message:异常信息

发生异常时该方法被回调。

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

data:服务器返回的二进制音频数据

当服务器有合成音频返回时被回调。

def on_close(self) -> None

当服务已经关闭连接后被回调。

响应结果

服务器返回二进制音频数据:

错误码

在使用API过程中,如果调用失败并返回错误信息,请参见错误信息进行解决。

更多示例

更多示例,请参见GitHub

常见问题

请参见GitHub QA

音色列表

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

说明

默认采样率代表当前音色的最佳采样率,缺省条件下默认按照该采样率输出,同时支持降采样或升采样。如龙小淳音色,默认采样率22.05 kHz,使用时可以降采样到8 kHz,但升采样到48 kHz时不会有额外效果提升。

音色

音频试听(右键保存音频)

model参数

voice参数

适用场景

语言

默认采样率(Hz)

默认音频格式

音色

音频试听(右键保存音频)

model参数

voice参数

适用场景

语言

默认采样率(Hz)

默认音频格式

龙婉

cosyvoice-v1

longwan

语音助手、

导航播报、

聊天数字人

中文普通话

22050

mp3

龙橙

cosyvoice-v1

longcheng

语音助手、

导航播报、

聊天数字人

中文普通话

22050

mp3

龙华

cosyvoice-v1

longhua

语音助手、

导航播报、

聊天数字人

中文普通话

22050

mp3

龙小淳

cosyvoice-v1

longxiaochun

语音助手、

导航播报、

聊天数字人

中文+英文

22050

mp3

龙小夏

cosyvoice-v1

longxiaoxia

语音助手、聊天数字人

中文

22050

mp3

龙小诚

cosyvoice-v1

longxiaocheng

语音助手、导航播报、聊天数字人

中文+英文

22050

mp3

龙小白

cosyvoice-v1

longxiaobai

聊天数字人、有声书、语音助手

中文

22050

mp3

龙老铁

cosyvoice-v1

longlaotie

新闻播报、有声书、语音助手、直播带货、导航播报

中文东北口音

22050

mp3

龙书

cosyvoice-v1

longshu

有声书、语音助手、导航播报、新闻播报、智能客服

中文

22050

mp3

龙硕

cosyvoice-v1

longshuo

语音助手、导航播报、新闻播报、客服催收

中文

22050

mp3

龙婧

cosyvoice-v1

longjing

语音助手、导航播报、新闻播报、客服催收

中文

22050

mp3

龙妙

cosyvoice-v1

longmiao

客服催收、导航播报、有声书、语音助手

中文

22050

mp3

龙悦

cosyvoice-v1

longyue

语音助手、诗词朗诵、有声书朗读、导航播报、新闻播报、客服催收

中文

22050

mp3

龙媛

cosyvoice-v1

longyuan

有声书、语音助手、聊天数字人

中文

22050

mp3

龙飞

cosyvoice-v1

longfei

会议播报、新闻播报、有声书

中文

22050

mp3

龙杰力豆

cosyvoice-v1

longjielidou

新闻播报、有声书、聊天助手

中文+英文

22050

mp3

龙彤

cosyvoice-v1

longtong

有声书、导航播报、聊天数字人

中文

22050

mp3

龙祥

cosyvoice-v1

longxiang

新闻播报、有声书、导航播报

中文

22050

mp3

Stella

cosyvoice-v1

loongstella

语音助手、直播带货、导航播报、客服催收、有声书

中文+英文

22050

mp3

Bella

cosyvoice-v1

loongbella

语音助手、客服催收、新闻播报、导航播报

中文

22050

mp3

升级CosyVoice2.0说明

部分音色支持升级使用CosyVoice2.0模型,升级方法:

  1. model字段替换为"cosyvoice-v2"

  2. voice字段使用CosyVoice2.0音色

升级后调用方法和计费不变,默认QPS3。支持升级的音色包括:

升级前voice参数

升级后voice参数

longcheng

longcheng_v2

longhua

longhua_v2

longshu

longshu_v2

loongbella

loongbella_v2

longwan

longwan_v2

longxiaochun

longxiaochun_v2

longxiaoxia

longxiaoxia_v2

更多的音色会陆续上线,敬请期待。

重要

目前cosyvoice-v2服务只支持使用主账号调用。

  • 本页导读 (1)
  • 前提条件
  • 快速开始
  • 同步调用
  • 异步调用
  • 流式调用
  • 请求参数
  • 关键接口
  • SpeechSynthesizer类
  • 回调接口(ResultCallback)
  • 响应结果
  • 错误码
  • 更多示例
  • 常见问题
  • 音色列表
  • 升级CosyVoice2.0说明
AI助理

点击开启售前

在线咨询服务

你好,我是AI助理

可以解答问题、推荐解决方案等