语音合成

语音合成模型（TTS）将文本转换为合成语音音频，支持标准模式和实时（流式输入）合成模式。AgentScope 当前提供以下模型类：

模型 API	模型类	说明
OpenAI	`OpenAITTSModel`	tts-1、tts-1-hd、gpt-4o-mini-tts；多种音色；可配置输出格式（mp3、wav、opus 等）
Gemini	`GeminiTTSModel`	gemini-2.5-flash-preview-tts、gemini-2.5-pro-preview-tts；30 种预设音色；流式输出
DashScope	`DashScopeTTSModel`	Qwen3-TTS，多种音色，流式输出
DashScope (Realtime)	`DashScopeRealtimeTTSModel`	Qwen3-TTS WebSocket 流式输入，适合对接大语言模型的流式输出
DashScope (CosyVoice)	`DashScopeCosyVoiceTTSModel`	CosyVoice-v3，支持标准与实时（流式输入）两种模式；cosyvoice-v3-flash/plus

创建模型

每个模型接收一个凭证、一个模型名，以及可选的 API 专属 Parameters 对象。下面的 tab 分别展示标准和实时两类初始化场景：

import os
from agentscope.tts import OpenAITTSModel
from agentscope.credential import OpenAICredential

tts = OpenAITTSModel(
    credential=OpenAICredential(api_key=os.environ["OPENAI_API_KEY"]),
    model="tts-1",
    parameters=OpenAITTSModel.Parameters(voice="alloy", response_format="mp3"),
    stream=True,
)

import os
from agentscope.tts import GeminiTTSModel
from agentscope.credential import GeminiCredential

tts = GeminiTTSModel(
    credential=GeminiCredential(api_key=os.environ["GEMINI_API_KEY"]),
    model="gemini-2.5-flash-preview-tts",
    parameters=GeminiTTSModel.Parameters(voice="Kore"),
    stream=True,
)

import os
from agentscope.tts import DashScopeTTSModel
from agentscope.credential import DashScopeCredential

tts = DashScopeTTSModel(
    credential=DashScopeCredential(api_key=os.environ["DASHSCOPE_API_KEY"]),
    model="qwen3-tts-flash",
    parameters=DashScopeTTSModel.Parameters(voice="Cherry"),
    stream=True,
)

import os
from agentscope.tts import DashScopeRealtimeTTSModel
from agentscope.credential import DashScopeCredential

tts = DashScopeRealtimeTTSModel(
    credential=DashScopeCredential(api_key=os.environ["DASHSCOPE_API_KEY"]),
    model="qwen3-tts-flash-realtime",
    parameters=DashScopeRealtimeTTSModel.Parameters(voice="Serena"),
    stream=True,
)

import os
from agentscope.tts import DashScopeCosyVoiceTTSModel
from agentscope.credential import DashScopeCredential

tts = DashScopeCosyVoiceTTSModel(
    credential=DashScopeCredential(api_key=os.environ["DASHSCOPE_API_KEY"]),
    model="cosyvoice-v3-flash",
    parameters=DashScopeCosyVoiceTTSModel.Parameters(voice="longanhuan"),
    stream=True,
)

import os
from agentscope.tts import DashScopeCosyVoiceTTSModel
from agentscope.credential import DashScopeCredential

tts = DashScopeCosyVoiceTTSModel(
    credential=DashScopeCredential(api_key=os.environ["DASHSCOPE_API_KEY"]),
    model="cosyvoice-v3-flash",
    parameters=DashScopeCosyVoiceTTSModel.Parameters(voice="longanhuan", realtime=True),
    stream=True,
)

所有语音合成模型通用的构造参数：

参数	类型	说明
`credential`	`CredentialBase`	API 专属凭证
`model`	`str`	模型标识符（如 `"qwen3-tts-flash"`）
`parameters`	`Parameters \| None`	API 专属参数，如 `voice`
`stream`	`bool`	是否流式输出音频

DashScopeRealtimeTTSModel 和 DashScopeCosyVoiceTTSModel（实时模式）的额外参数：

参数	类型	默认值	说明
`cold_start_length`	`int \| None`	`None`	首次向 API 发送前的最小字符数
`cold_start_words`	`int \| None`	`None`	首次发送前的最小词数
`max_retries`	`int`	`3`	WebSocket 失败最大重试次数
`retry_delay`	`float`	`5.0`	初始重试延迟（秒，指数退避）

调用模型

通过 synthesize() 方法合成语音：

async def synthesize(
    self,
    text: str | None = None,
    **kwargs: Any,
) -> TTSResponse | AsyncGenerator[TTSResponse, None]:

返回类型取决于 stream 设置：

stream=False：返回单个 TTSResponse，包含完整音频。
stream=True：返回 AsyncGenerator[TTSResponse, None]，每个 chunk 携带增量音频；最后一个 chunk 的 is_last=True。

每个 TTSResponse 包含：

字段	类型	说明
`content`	`DataBlock \| None`	音频数据，格式由 `content.source.media_type` 指示（如 `"audio/wav"`、`"audio/pcm;rate=24000"`）
`is_last`	`bool`	是否为流式最后一个 chunk
`usage`	`TTSUsage \| None`	token 统计（`input_tokens`、`output_tokens`）和耗时 `time`（秒）
`id`	`str`	自动生成的唯一标识
`metadata`	`dict \| None`	可选的 API 专属元数据

import asyncio
import os
from agentscope.tts import OpenAITTSModel
from agentscope.credential import OpenAICredential

async def main():
    tts = OpenAITTSModel(
        credential=OpenAICredential(api_key=os.environ["OPENAI_API_KEY"]),
        model="tts-1",
        parameters=OpenAITTSModel.Parameters(voice="alloy"),
        stream=True,
    )

    async for chunk in await tts.synthesize("你好，世界！"):
        if chunk.content:
            # chunk.content 是包含 base64 编码 audio/mpeg 数据的 DataBlock
            print(f"音频 chunk: {len(chunk.content.source.data)} bytes")

asyncio.run(main())

import asyncio
import os
from agentscope.tts import GeminiTTSModel
from agentscope.credential import GeminiCredential

async def main():
    tts = GeminiTTSModel(
        credential=GeminiCredential(api_key=os.environ["GEMINI_API_KEY"]),
        model="gemini-2.5-flash-preview-tts",
        parameters=GeminiTTSModel.Parameters(voice="Kore"),
        stream=True,
    )

    async for chunk in await tts.synthesize("你好，世界！"):
        if chunk.content:
            # chunk.content 是包含 base64 编码 audio/wav 数据的 DataBlock
            print(f"音频 chunk: {len(chunk.content.source.data)} bytes")

asyncio.run(main())

import asyncio
import os
from agentscope.tts import DashScopeTTSModel
from agentscope.credential import DashScopeCredential

async def main():
    tts = DashScopeTTSModel(
        credential=DashScopeCredential(api_key=os.environ["DASHSCOPE_API_KEY"]),
        model="qwen3-tts-flash",
        parameters=DashScopeTTSModel.Parameters(voice="Cherry"),
        stream=True,
    )

    # 流式合成
    async for chunk in await tts.synthesize("你好，世界！"):
        if chunk.content:
            # chunk.content 是包含 base64 编码 audio/wav 数据的 DataBlock
            print(f"音频 chunk: {len(chunk.content.source.data)} bytes")

asyncio.run(main())

实时合成（流式输入）

实时模型（DashScopeRealtimeTTSModel 和 realtime=True 的 DashScopeCosyVoiceTTSModel）支持增量推送文本，典型场景是对接大语言模型的流式输出。两者共享相同的 push() / synthesize() 接口，通过 async with 或手动调用 connect() / close() 管理生命周期：

DashScopeRealtimeTTSModel（Qwen3）以 token 级别粒度产出音频，每次 push() 通常都能返回音频数据。而 realtime=True 的 DashScopeCosyVoiceTTSModel 依赖 CosyVoice 服务端自动分句后才进行合成，音频只在检测到完整句子边界后才返回，因此 push() 对不完整的句子可能返回空响应。调用 synthesize() 会强制合成所有剩余文本（包括未完成的句子）。

import asyncio
import os
from agentscope.tts import DashScopeRealtimeTTSModel
from agentscope.credential import DashScopeCredential

async def main():
    tts = DashScopeRealtimeTTSModel(
        credential=DashScopeCredential(api_key=os.environ["DASHSCOPE_API_KEY"]),
        model="qwen3-tts-flash-realtime",
        parameters=DashScopeRealtimeTTSModel.Parameters(voice="Cherry"),
        stream=True,
    )

    async with tts:
        # 增量推送文本，每次 push() 返回当前已可用的音频
        # （尚无音频时 content=None）
        resp1 = await tts.push("你好，")
        if resp1.content:
            print("第一次 push 后有音频")

        resp2 = await tts.push("今天过得怎么样？")
        if resp2.content:
            print("第二次 push 后有音频")

        # 结束：刷新剩余缓冲文本并收集最终音频。
        # text= 可选：传入则先追加再结束；
        # 不传则只结束之前 push 的文本。
        response = await tts.synthesize()

asyncio.run(main())

实时模式的生命周期方法：

方法	说明
`connect()`	打开 WebSocket 连接
`push(text)`	增量追加文本（非阻塞），返回当前已可用的音频
`synthesize()`	结束合成，返回剩余音频
`close()`	断开连接

与智能体集成

在智能体层，语音合成通过 TTSMiddleware 集成，它会拦截智能体的文本输出并自动合成语音：

from agentscope.agent import Agent
from agentscope.middleware import TTSMiddleware
from agentscope.tts import DashScopeTTSModel
from agentscope.credential import DashScopeCredential

agent = Agent(
    name="assistant",
    model=chat_model,
    middlewares=[
        TTSMiddleware(
            DashScopeTTSModel(
                credential=DashScopeCredential(api_key="..."),
                model="qwen3-tts-flash",
                parameters=DashScopeTTSModel.Parameters(voice="Cherry"),
                stream=True,
            ),
        ),
    ],
)

# 智能体的回复流中同时包含文本和音频事件
async for event in agent.reply_stream(user_msg):
    # TextBlockDeltaEvent：文本内容
    # DataBlockDeltaEvent：音频内容（WAV）
    ...

中间件会根据模型类型自动选择最优合成策略：

模型类型	中间件行为
标准模式	等待完整文本生成后一次性合成
实时模式	随文本增量到达实时推送，并发流式返回音频

TTS 模型卡片

TTSModelCard 描述语音合成模型的能力（可用音色、流式支持与参数范围），其 schema 与覆盖机制与通用的模型卡片一致。每张卡片由模型实现旁的 YAML 文件定义，下面的 tab 分别展示各模型 API 的一张卡片：

name: tts-1
label: TTS-1
status: active
input_types:
  - text/plain
output_types:
  - audio/mpeg
  - audio/opus
  - audio/aac
  - audio/flac
  - audio/wav
  - audio/pcm
voices:
  - alloy
  - ash
  - ballad
  - coral
  - echo
  - fable
  - onyx
  - nova
  - sage
  - shimmer
  - verse
parameter_overrides:
  instructions:
    hidden: true

name: gemini-2.5-flash-preview-tts
label: Gemini 2.5 Flash Preview TTS
status: active
input_types:
  - text/plain
output_types:
  - audio/wav
voices:
  - Zephyr
  - Puck
  - Charon
  - Kore
  - Fenrir
  - Leda
  - Orus
  - Aoede
parameter_overrides: {}

name: qwen3-tts-flash
label: Qwen3-TTS-Flash
status: active
input_types:
  - text/plain
output_types:
  - audio/wav
voices:
  - Cherry
  - Serena
  - Ethan
  - Chelsie
parameter_overrides: {}

name: cosyvoice-v3-flash
label: CosyVoice-v3-Flash
status: active
input_types:
  - text/plain
output_types:
  - audio/wav
voices:
  - longanhuan
  - longanyang
  - longhuhu_v3
  - longyingmu_v3
  - longxiaochun_v3
  - longxiaoxia_v3
  - longlaotie_v3
  - longshuo_v3
  - longshu_v3
parameter_overrides: {}

voices 列表会自动作为 voice 字段的 enum 约束注入 parameter_schema，前端据此渲染下拉选择器。

字段	类型	说明
`name`	`str`	模型标识符（如 `"qwen3-tts-flash"`）
`label`	`str`	显示名称（如 `"Qwen3-TTS-Flash"`）
`status`	`str`	`"active"`、`"deprecated"` 或 `"sunset"`
`realtime`	`bool`	是否支持流式输入
`input_types`	`list[str]`	接受的输入 MIME 类型（固定 `["text/plain"]`）
`output_types`	`list[str]`	输出 MIME 类型（通常 `["audio/wav"]`）
`parameter_schema`	`dict`	合并后的 JSON Schema：基于 `Parameters` 类生成，并注入 YAML 中的 `voices` enum
`parameters_overrides`	`dict`	逐模型覆盖（语法与 Chat 模型卡片一致）

通过凭证获取语音合成模型卡片：

from agentscope.credential import DashScopeCredential, GeminiCredential

cards = DashScopeCredential.list_tts_models()
for card in cards:
    print(f"{card.name} (realtime={card.realtime}): {card.label}")

# Gemini TTS 模型卡片
gemini_cards = GeminiCredential.list_tts_models()

或直接通过模型类：

from agentscope.tts import OpenAITTSModel, GeminiTTSModel, DashScopeTTSModel, DashScopeCosyVoiceTTSModel

# OpenAI TTS 模型
openai_cards = OpenAITTSModel.list_models()

# Gemini TTS 模型
gemini_cards = GeminiTTSModel.list_models()

# Qwen3 TTS 模型
cards = DashScopeTTSModel.list_models()

# CosyVoice 模型
cosyvoice_cards = DashScopeCosyVoiceTTSModel.list_models()

自定义模型 API

接入新的语音合成 API，需实现 TTSModelBase 子类并在凭证上注册：

from typing import Literal, Type, TYPE_CHECKING, AsyncGenerator, Any
from pydantic import BaseModel, Field
from agentscope.tts import TTSModelBase, TTSResponse
from agentscope.credential import CredentialBase

if TYPE_CHECKING:
    from agentscope.tts import TTSModelBase as TTSBase

class MyTTSModel(TTSModelBase):
    class Parameters(BaseModel):
        voice: str = Field(default="default", title="Voice")

    type: Literal["my_tts"] = "my_tts"

    async def synthesize(
        self, text: str | None = None, **kwargs: Any
    ) -> TTSResponse | AsyncGenerator[TTSResponse, None]:
        # 调用你的模型 API
        ...

# 在凭证上注册
class MyCredential(CredentialBase):
    @classmethod
    def get_tts_model_classes(cls) -> list[Type["TTSBase"]]:
        return [MyTTSModel]

快速开始

核心模块

智能体即服务

其他

创建模型

调用模型

实时合成（流式输入）

与智能体集成

TTS 模型卡片

自定义模型 API

​创建模型

​调用模型

​实时合成（流式输入）

​与智能体集成

​TTS 模型卡片

​自定义模型 API

创建模型

调用模型

实时合成（流式输入）

与智能体集成

TTS 模型卡片

自定义模型 API