Skip to main content
A TTS Model converts text into synthesized speech audio, supporting both standard and realtime (streaming-input) synthesis modes. AgentScope currently ships the following TTS model classes:

MiniMax And Gemini 3.8

MiniMaxTTSModel uses MiniMaxCredential, defaults to speech-2.8-hd, and supports complete-text synthesis with optional streamed output:
GeminiTTSModel also supports gemini-3.8-flash-tts and gemini-3.8-flash-lite-tts. Use the selected model card’s parameter schema to discover available voices and controls.

Clone And Reuse Voices

The agentscope.tts package exports DashScopeVoiceCloningClient and OpenAIVoiceCloningClient. Their create_voice() methods return a provider voice ID and do not require the Agent Service. For DashScope, set Parameters(target_model=...). Qwen models accept sample audio bytes with a filename; CosyVoice requires a public audio_url. Reuse the same credential and target model for synthesis, passing the returned ID as Parameters(voice=voice_id). For OpenAI, upload the required speaker consent recording with create_consent(), then supply its ID in Parameters(name=..., consent=...) when calling create_voice() with sample audio bytes. A compatible OpenAITTSModel takes voice={"id": voice_id}. The Agent Service stores reusable voice profiles and exposes engine discovery, cloning, and consent endpoints.

Create TTS Model

Every TTS model takes a credential, a model name, and an optional provider-specific Parameters object. The tabs below show the standard and realtime setups:
Common constructor arguments shared by every TTS model: Additional arguments for DashScopeRealtimeTTSModel and DashScopeCosyVoiceTTSModel (realtime mode):

Call TTS Model

Invoke the model by calling synthesize() with the text to speak:
The return type follows the model’s stream setting:
  • stream=False: returns a single TTSResponse with the complete audio.
  • stream=True: returns an AsyncGenerator[TTSResponse, None]. Each chunk carries an incremental audio delta; the final chunk has is_last=True.
Each TTSResponse carries:

Realtime TTS (Streaming Input)

For realtime models (DashScopeRealtimeTTSModel and DashScopeCosyVoiceTTSModel with realtime=True), text can be pushed incrementally as it arrives from a streaming LLM. Both share the same push() / synthesize() interface. The lifecycle is managed via async with or manual connect() / close():
DashScopeRealtimeTTSModel (Qwen3) produces audio at token-level granularity, so each push() call typically returns audio data. In contrast, DashScopeCosyVoiceTTSModel with realtime=True relies on the CosyVoice server which automatically segments text into sentences before synthesizing. Audio is only returned after a complete sentence boundary is detected, so push() may return empty responses for partial sentences. Calling synthesize() forces synthesis of all remaining text including incomplete sentences.
The realtime lifecycle methods:

Integrate with Agent

In the agent layer, TTS is integrated via TTSMiddleware, which intercepts the agent’s text output and synthesizes speech automatically:
The middleware automatically selects the optimal synthesis strategy:

TTS Model Card

TTSModelCard describes a TTS model’s capabilities (available voices, streaming support, and parameter ranges) and follows the same schema and override mechanics as the general ModelCard. Each card is defined by a YAML file alongside the model implementation. The tabs below show one card per provider:
The voices list is automatically injected into the parameter_schema as an enum constraint on the voice field, so the frontend renders a dropdown selector. Retrieve TTS model cards via the credential:
Or directly on the model class:

Custom TTS Provider

To add a new TTS provider, implement a TTSModelBase subclass and register it on the credential: