非实时语音合成CosyVoice Python SDK参考

call() - 语音合成调用

方法签名：

@classmethod
def call(cls, model: str, text: str, voice: str,
         format: str = "wav", sample_rate: int = 24000,
         volume: int = 50, rate: float = 1.0, pitch: float = 1.0,
         bit_rate: int = 32, enable_ssml: bool = False,
         word_timestamp_enabled: bool = False,
         seed: int = 0, language_hints: list = None,
         instruction: str = None,
         enable_aigc_tag: bool = False,
         aigc_propagator: str = None,
         aigc_propagate_id: str = None,
         hot_fix: dict = None,
         enable_markdown_filter: bool = False,
         stream: bool = False,
         api_key: str = None, **kwargs)

参数说明：

"hot_fix": {
  "pronunciation": [
    {"天气": "tian1 qi4"}
  ],
  "replace": [
    {"今天": "金天"}
  ]
}

返回值：

• 非流式模式（stream=False）：返回结果对象，包含以下属性：

  • audio_url：音频下载URL（有效期有限）。

  • audio_id：音频ID。

  • expires_at：URL过期时间。

• 流式模式（stream=True）：返回迭代器，每个元素包含以下属性：

  • audio_data：当前分片的音频二进制数据（bytes）。

  • sentences：句子级别的合成信息（如有）。

  重要

  流式模式下，迭代器的最后一个元素除了包含音频数据分片外，还会额外返回audio_url（完整音频的下载地址）。如果在拼接音频数据时不跳过该元素，会导致最终生成的音频中同一段内容重复播放。因此在遍历迭代器时，需通过not chunk.audio_url条件过滤包含完整音频URL的最后一个元素。

非流式调用

非流式调用设置stream=False，等待合成完成后返回音频URL，通过URL下载音频文件。

# -*- coding: utf-8 -*-
import os
from dashscope.audio.http_tts.http_speech_synthesizer import HttpSpeechSynthesizer

# 未配置环境变量时，将下行替换为：api_key = "sk-xxx"，即替换为实际的API Key
api_key = os.getenv("DASHSCOPE_API_KEY")

# 非流式调用，返回音频URL
result = HttpSpeechSynthesizer.call(
    model="cosyvoice-v3-flash",  # 更换模型时，需同步更换为对应版本的音色
    text="今天是个好日子，适合构建人们喜爱的产品！",
    voice="longanhuan",  # 该音色适用于cosyvoice-v3系列，cosyvoice-v2请使用longxiaochun_v2等v2音色
    format="wav",
    sample_rate=24000,
    stream=False,
    api_key=api_key,
)

# 获取音频URL
print(f"音频 URL: {result.audio_url}")
print(f"音频 ID: {result.audio_id}")
if result.audio_id:
    request_id = result.audio_id.removeprefix("audio_")
    print(f"请求 Id: {request_id}")
print(f"过期时间: {result.expires_at}")

流式调用

流式调用设置stream=True，返回迭代器，逐段获取音频数据。适用于对首包延迟有要求的实时播放场景。流式模式下，迭代器的最后一个元素会额外返回完整音频的audio_url，遍历时需通过not chunk.audio_url过滤该元素，避免音频内容重复。

# -*- coding: utf-8 -*-
import os
from dashscope.audio.http_tts.http_speech_synthesizer import HttpSpeechSynthesizer

# 未配置环境变量时，将下行替换为：api_key = "sk-xxx"，即替换为实际的API Key
api_key = os.getenv("DASHSCOPE_API_KEY")

# 流式调用，逐段返回音频数据
stream_result = HttpSpeechSynthesizer.call(
    model="cosyvoice-v3-flash",  # 更换模型时，需同步更换为对应版本的音色
    text="今天是个好日子，适合构建人们喜爱的产品！",
    voice="longanhuan",  # 该音色适用于cosyvoice-v3系列，cosyvoice-v2请使用longxiaochun_v2等v2音色
    format="wav",
    sample_rate=24000,
    stream=True,
    api_key=api_key,
)

# 遍历迭代器，逐段接收音频数据
audio_chunks = []
for chunk in stream_result:
    if not chunk.audio_url and chunk.audio_data:  # 过滤最后一个包含完整音频URL的chunk，避免音频重复
        audio_chunks.append(chunk.audio_data)
        print(f"收到音频数据块，大小: {len(chunk.audio_data)} bytes")

    if chunk.sentences:
        print(f"句子信息: {chunk.sentences}")
    
    if chunk.audio_id:
        print(f"Audio ID: {chunk.audio_id}")
        request_id = chunk.audio_id.removeprefix("audio_")
        print(f"请求 Id: {request_id}")

# 合并所有音频数据并保存
full_audio = b"".join(audio_chunks)
print(f"总音频大小: {len(full_audio)} bytes")

with open("output.wav", "wb") as f:
    f.write(full_audio)
print("音频已保存到 output.wav")