python实现百炼平台tts语音合成接入

️ DashScope 语音合成（TTS）从入门到实践教程

本教程将带你快速掌握如何使用 DashScope 的 SpeechSynthesizer 类实现语音合成，涵盖三种调用方式（同步、异步、流式），附带完整代码示例和关键注意事项。

---

一、前置准备

1. 安装依赖

确保已安装 Python 3.7+，并通过 pip 安装 DashScope SDK：

pip install dashscope

若需流式调用实时播放音频（如示例中的 pyaudio），还需安装：

• ​​macOS​​:

  brew install portaudio && pip install pyaudio

• ​​Linux (Debian/Ubuntu)​​:

  sudo apt-get install python-pyaudio python3-pyaudio && pip install pyaudio

• ​​Windows​​:

  pip install pyaudio

2. 获取 API Key

• 登录 DashScope 控制台，在「API 密钥管理」中获取 API Key。
• 
• 若未将 API Key 配置到环境变量，需在代码中显式设置：

  import dashscope
  dashscope.api_key = "your-api-key"  # 替换为你的实际 Key

---

二、核心类与参数说明

1. SpeechSynthesizer 类

用于语音合成的核心类，初始化时需指定关键参数：

from dashscope.audio.tts_v2 import SpeechSynthesizer

synthesizer = SpeechSynthesizer(
    model="cosyvoice-v2",      # 模型名称（必填）
    voice="longxiaochun_v2",   # 音色（必填）
    format=AudioFormat.PCM_22050HZ_MONO_16BIT  # 仅流式调用需指定音频格式
)

​​关键参数​​：

参数	说明
model	使用的模型（如 cosyvoice-v2）
voice	音色（如 longxiaochun_v2）
format	音频格式（流式调用需设为 PCM_22050HZ_MONO_16BIT，其他调用方式可忽略）

---

三、三种调用方式详解

方式 1️⃣：同步调用（阻塞式，适合短文本）

​​特点​​：

• 客户端提交文本后阻塞等待，服务端一次性返回完整音频数据。
• 不支持流式中间结果，适合对实时性要求不高的场景（如生成短语音文件）。

​​代码示例​​：

from dashscope.audio.tts_v2 import SpeechSynthesizer

# 初始化合成器
synthesizer = SpeechSynthesizer(model="cosyvoice-v2", voice="longxiaochun_v2")

# 同步调用：提交文本，获取二进制音频
audio_data = synthesizer.call("今天天气怎么样？")  # 文本长度需 ≤2000 字符

# 保存音频到本地
with open("output_sync.mp3", "wb") as f:
    f.write(audio_data)

# 打印请求指标
print(f"[Metric] 请求ID: {synthesizer.get_last_request_id()}, 首包延迟: {synthesizer.get_first_package_delay()}毫秒")

---

方式 2️⃣：异步调用（回调流式，适合实时性要求高的短文本）

​​特点​​：

• 客户端通过实现 ResultCallback 接口，以回调方式逐步接收音频数据流。
• 虽然也是“一次性”提交文本，但结果通过回调实时返回，适合需要边合成边处理的场景（如实时播放）。

​​代码示例​​：

from dashscope.audio.tts_v2 import SpeechSynthesizer, ResultCallback
from datetime import datetime

# 自定义回调类：将音频写入文件
class AudioFileCallback(ResultCallback):
    def __init__(self):
        self.file = None

    def on_open(self):
        print("连接建立")
        self.file = open("output_async.mp3", "wb")

    def on_complete(self):
        print("语音合成完成")

    def on_error(self, message: str):
        print(f"合成异常: {message}")

    def on_close(self):
        print("连接关闭")
        if self.file:
            self.file.close()

    def on_data(self, data: bytes) -> None:
        self.file.write(data)
        print(f"收到音频数据块，长度: {len(data)} 字节")

# 初始化回调与合成器
callback = AudioFileCallback()
synthesizer = SpeechSynthesizer(
    model="cosyvoice-v2",
    voice="longxiaochun_v2",
    callback=callback  # 绑定回调接口
)

# 触发合成（音频通过回调逐步写入文件）
synthesizer.call("今天天气怎么样？")

# 打印请求指标
print(f"[Metric] 请求ID: {synthesizer.get_last_request_id()}, 首包延迟: {synthesizer.get_first_package_delay()}毫秒")

---

方式 3️⃣：流式调用（分片提交，适合长文本实时合成）

​​特点​​：

• 支持将长文本分多次（片段）提交，服务端实时合成并回调返回音频。
• 允许文本分段发送，服务端收到部分文本后立即开始处理，适合实时性要求高的长文本场景（如 LLM 流式生成语音）。

​​关键限制​​：

• 单次 streaming_call 提交的文本长度 ≤2000 字符。
• 累计提交的总文本长度 ≤20 万字符。
• 文本发送间隔不得超过 23 秒，否则触发超时异常。
• 必须调用 streaming_complete() 结束任务，否则结尾文本可能无法合成！

​​代码示例​​：

import time
import pyaudio
from dashscope.audio.tts_v2 import SpeechSynthesizer, ResultCallback, AudioFormat

# 自定义回调类：实时播放音频
class AudioPlayCallback(ResultCallback):
    def __init__(self):
        self._player = None
        self._stream = None

    def on_open(self):
        print("连接建立")
        self._player = pyaudio.PyAudio()
        self._stream = self._player.open(
            format=pyaudio.paInt16,
            channels=1,
            rate=22050,
            output=True
        )

    def on_complete(self):
        print("语音合成完成")

    def on_error(self, message: str):
        print(f"合成异常: {message}")

    def on_close(self):
        print("连接关闭")
        if self._stream:
            self._stream.stop_stream()
            self._stream.close()
        if self._player:
            self._player.terminate()

    def on_data(self, data: bytes) -> None:
        self._stream.write(data)
        print(f"收到音频数据块，长度: {len(data)} 字节")

# 初始化回调与合成器
callback = AudioPlayCallback()
synthesizer = SpeechSynthesizer(
    model="cosyvoice-v2",
    voice="longxiaochun_v2",
    format=AudioFormat.PCM_22050HZ_MONO_16BIT,  # 流式调用必须指定格式
    callback=callback
)

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

# 分片提交文本（每次调用 streaming_call）
for text in test_text:
    synthesizer.streaming_call(text)  # 提交文本片段
    time.sleep(0.1)  # 模拟处理间隔（需控制间隔 ≤23秒）

# 结束任务（必须调用！否则结尾文本可能无法合成）
synthesizer.streaming_complete()

# 打印请求指标
print(f"[Metric] 请求ID: {synthesizer.get_last_request_id()}, 首包延迟: {synthesizer.get_first_package_delay()}毫秒")

---

四、关键注意事项

1. ​​API Key 配置​​

   • 若未通过环境变量配置，必须在代码中显式设置 dashscope.api_key。

2. ​​文本长度限制​​

   • 同步/异步调用：单次文本 ≤2000 字符。
   • 流式调用：单次 streaming_call ≤2000 字符，累计 ≤20 万字符。

3. ​​超时机制​​

   • 流式调用中，两次 streaming_call 的间隔不得超过 23 秒，否则触发超时异常。

4. ​​必须调用 streaming_complete()​​

   • 流式任务结束时务必调用此方法，否则服务端可能不会处理剩余未合成的文本！

5. ​​音频格式兼容性​​

   • 流式调用需显式设置 format=AudioFormat.PCM_22050HZ_MONO_16BIT，其他调用方式无需指定。

---

五、总结

场景	推荐调用方式
短文本、离线生成音频文件	同步调用
短文本、需实时播放音频	异步调用
长文本、需实时流式播放	流式调用