跳转到主要内容
语音合成模型(TTS)将文本转换为合成语音音频,支持标准模式和实时(流式输入)合成模式。AgentScope 当前提供以下模型类:

MiniMax 与 Gemini 3.8

MiniMaxTTSModel 使用 MiniMaxCredential,默认模型为 speech-2.8-hd,接收完整文本并支持流式输出:
GeminiTTSModel 还支持 gemini-3.8-flash-tts 和 gemini-3.8-flash-lite-tts。可用音色和控制参数以所选模型卡片的参数 schema 为准。

克隆并复用音色

agentscope.tts 导出 DashScopeVoiceCloningClient 和 OpenAIVoiceCloningClient。两者的 create_voice() 方法返回模型 API 的音色 ID, 无需依赖智能体服务。 DashScope 需要设置 Parameters(target_model=...)。Qwen 模型接收音频字节和文件名, CosyVoice 则要求公开可访问的 audio_url。合成时复用相同凭证与目标模型, 将返回的 ID 作为 Parameters(voice=voice_id) 传入。 OpenAI 需要先通过 create_consent() 上传说话者授权录音,再将授权 ID 放入 Parameters(name=..., consent=...),并传入样本音频字节调用 create_voice()。 支持自定义音色的 OpenAITTSModel 使用 voice={"id": voice_id}。 智能体服务 提供音色档案持久化,以及可用引擎发现、音色克隆和授权录音接口。

创建模型

每个模型接收一个凭证、一个模型名,以及可选的 API 专属 Parameters 对象。下面的 tab 分别展示标准和实时两类初始化场景:
所有语音合成模型通用的构造参数: DashScopeRealtimeTTSModel 和 DashScopeCosyVoiceTTSModel(实时模式)的额外参数:

调用模型

通过 synthesize() 方法合成语音:
返回类型取决于 stream 设置:
  • stream=False:返回单个 TTSResponse,包含完整音频。
  • stream=True:返回 AsyncGenerator[TTSResponse, None],每个 chunk 携带增量音频;最后一个 chunk 的 is_last=True。
每个 TTSResponse 包含:

实时合成(流式输入)

实时模型(DashScopeRealtimeTTSModel 和 realtime=True 的 DashScopeCosyVoiceTTSModel)支持增量推送文本,典型场景是对接大语言模型的流式输出。两者共享相同的 push() / synthesize() 接口,通过 async with 或手动调用 connect() / close() 管理生命周期:
DashScopeRealtimeTTSModel(Qwen3)以 token 级别粒度产出音频,每次 push() 通常都能返回音频数据。而 realtime=True 的 DashScopeCosyVoiceTTSModel 依赖 CosyVoice 服务端自动分句后才进行合成,音频只在检测到完整句子边界后才返回,因此 push() 对不完整的句子可能返回空响应。调用 synthesize() 会强制合成所有剩余文本(包括未完成的句子)。
实时模式的生命周期方法:

与智能体集成

在智能体层,语音合成通过 TTSMiddleware 集成,它会拦截智能体的文本输出并自动合成语音:
中间件会根据模型类型自动选择最优合成策略:

TTS 模型卡片

TTSModelCard 描述语音合成模型的能力(可用音色、流式支持与参数范围),其 schema 与覆盖机制与通用的模型卡片一致。每张卡片由模型实现旁的 YAML 文件定义,下面的 tab 分别展示各模型 API 的一张卡片:
voices 列表会自动作为 voice 字段的 enum 约束注入 parameter_schema,前端据此渲染下拉选择器。 通过凭证获取语音合成模型卡片:
或直接通过模型类:

自定义模型 API

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