> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For AgentScope Python, use https://docs.agentscope.io/stable/en/index for new projects. For existing projects, check the installed agentscope version and use matching versioned documentation.
> The /latest/ alias points to the newest documentation and may move ahead of /stable/ when a development version exists. Do not mix AgentScope 1.x and 2.x APIs.
> State the AgentScope version when providing installation commands or code examples. ReMe uses its own continuously updated /reme/latest/ documentation.

# Overview

> Connect model providers with a credential and discover their models through model cards

The model layer connects AgentScope to model providers through a two-tier hierarchy. A **Credential** sits at the top, with the model families the provider exposes beneath it: **LLM (Chat Model)**, **TTS**, **ASR**, **Embedding**, and **Realtime Model**.

A **Credential** carries the API authentication fields a provider requires (`api_key`, `base_url`, ...). From a single credential, you can discover every model the provider offers in each family it supports. The table below shows each built-in credential and the model classes under it:

| Credential | LLM (Chat Model) | TTS | ASR | Embedding | Realtime |
| - | - | - | - | - | - |
| `DashScopeCredential` | `DashScopeChatModel` | `DashScopeTTSModel` `DashScopeRealtimeTTSModel` `DashScopeCosyVoiceTTSModel` | — | `DashScopeEmbeddingModel` | `DashScopeRealtimeModel` `DashScopeAudioRealtimeModel` |
| `OpenAICredential` | `OpenAIChatModel` `OpenAIResponseModel` | `OpenAITTSModel` | `OpenAIASRModel` | `OpenAIEmbeddingModel` | `OpenAIRealtimeModel` |
| `GeminiCredential` | `GeminiChatModel` | `GeminiTTSModel` | — | `GeminiEmbeddingModel` | `GeminiRealtimeModel` |
| `AnthropicCredential` | `AnthropicChatModel` | — | — | — | — |
| `DeepSeekCredential` | `DeepSeekChatModel` | — | — | — | — |
| `MoonshotCredential` | `MoonshotChatModel` | — | — | — | — |
| `VolcengineCredential` | `VolcengineChatModel` | — | — | — | — |
| `XAICredential` | `XAIChatModel` | — | — | — | `XAIRealtimeModel` |
| `OllamaCredential` | `OllamaChatModel` | — | — | `OllamaEmbeddingModel` | — |

This layering mirrors the natural frontend flow (register a credential first, then pick a model from under it), letting the UI authenticate once and surface every model family the provider supports.

All model families share the same construction pattern: a model takes a **credential**, a **model name**, and an optional provider-specific **`Parameters`** object. Each family page covers its own creation and invocation details:

* [LLM](https://docs.agentscope.io/en/versions/2.0.11/building-blocks/model/llm.md): drives an agent's conversation and tool calls
* [TTS](https://docs.agentscope.io/en/versions/2.0.11/building-blocks/model/tts.md): converts text into synthesized speech audio
* [ASR](https://docs.agentscope.io/en/versions/2.0.11/building-blocks/model/asr.md): transcribes speech audio into text
* [Embedding](https://docs.agentscope.io/en/versions/2.0.11/building-blocks/model/embedding.md): converts text and media into dense vectors

> [!TIP]
>
> **Realtime Model** powers speech-to-speech voice conversations. See [Speech-to-Speech](https://docs.agentscope.io/en/versions/2.0.11/building-blocks/realtime/speech-to-speech.md) for how to create and use one.

## Integrate with Frontend

### What is ModelCard

A model card is a declarative description of a model's capabilities and constraints, designed to drive the frontend: model selectors, parameter forms, and feature toggles can be rendered dynamically without hardcoding any provider-specific knowledge. Each model family has its own card class:

| Card Class | Family | `type` Discriminator |
| - | - | - |
| `ModelCard` | LLM (chat model) | `"chat_model"` |
| `TTSModelCard` | TTS | `"tts_model"` |
| `ASRModelCard` | ASR | `"asr_model"` |
| `EmbeddingModelCard` | Embedding | `"embedding_model"` |

Chat, TTS, and embedding cards share the following core fields. ASR cards
use the same `name`, `label`, `input_types`, `output_types`, and
`parameter_schema` fields, but do not currently expose lifecycle status or
per-model parameter overrides.

| Field | Type | Description |
| - | - | - |
| `name` | `str` | Model identifier (e.g. `"claude-sonnet-4-6"`) |
| `label` | `str` | Human-readable display name (e.g. `"Claude Sonnet 4.6"`) |
| `status` | `"active" \| "deprecated" \| "sunset"` | Model lifecycle status |
| `input_types` | `list[str]` | Accepted input MIME types, used by the frontend to filter attachment uploads (e.g. only show an image button when `image/*` is supported) |
| `output_types` | `list[str]` | Output MIME types the model can produce, advertising capabilities such as a thinking toggle when `application/x-thinking` is present |
| `parameter_schema` | `dict` | Final JSON Schema for the parameter form: base schema merged with per-model overrides (see below) |
| `parameter_overrides` | `dict[str, dict]` | The raw per-model overrides from the YAML, before merging |

On top of the common core, each card type adds family-specific fields:

| Card Class | Family-Specific Fields |
| - | - |
| `ModelCard` | `model_class` (implementation discriminator, e.g. `openai_chat` or `openai_response`), `context_size` (max context window in tokens), `output_size` (max output tokens), `deprecated_at` (deprecation date) |
| `TTSModelCard` | `realtime` (whether the model supports streaming input), `deprecated_at`; the YAML's `voices` list is injected into `parameter_schema` as an enum on the `voice` field |
| `ASRModelCard` | `realtime` (whether the model accepts streaming audio input) |
| `EmbeddingModelCard` | `dimensions` (default output vector size, required), `supported_dimensions` (allowed sizes for Matryoshka-style models, `None` = fixed), `context_size` (optional) |

`input_types` and `output_types` use MIME types to describe modality. Common values:

| MIME Type | Meaning |
| - | - |
| `text/plain` | Text |
| `application/x-thinking` | Reasoning / chain-of-thought |
| `application/x-embedding` | Dense vector embedding |
| `image/*` (e.g. `image/png`, `image/jpeg`) | Image |
| `audio/*` (e.g. `audio/wav`, `audio/mp3`) | Audio |
| `video/*` (e.g. `video/mp4`) | Video |

Each card is defined by a YAML file that ships alongside the model implementation. The tabs below show a real card from each family:

```yaml Chat (claude-sonnet-4-6) theme={null}
name: claude-sonnet-4-6
label: Claude Sonnet 4.6
status: active

input_types:
  - text/plain
  - application/x-thinking
  - image/jpeg
  - image/png
  - image/gif
  - image/webp

output_types:
  - text/plain
  - application/x-thinking

context_size: 1000000
output_size: 65536

parameter_overrides:
  max_tokens: {"maximum": 65536}
```

```yaml TTS (qwen3-tts-flash) theme={null}
name: qwen3-tts-flash
label: Qwen3-TTS-Flash
status: active

input_types:
  - text/plain

output_types:
  - audio/wav

# Injected into parameter_schema as an enum on the voice field,
# so the frontend renders a dropdown selector.
voices:
  - Cherry
  - Serena
  - Ethan
  - Chelsie

parameter_overrides: {}
```

```yaml Embedding (text-embedding-v4) theme={null}
name: text-embedding-v4
label: Text Embedding v4
status: active

input_types:
  - text/plain

output_types:
  - application/x-embedding

context_size: 8192

# Default output vector size, plus the sizes this
# Matryoshka-style model can be truncated to.
dimensions: 1024
supported_dimensions: [2048, 1536, 1024, 768, 512, 256, 128, 64]
```

```yaml ASR (gpt-4o-mini-transcribe) theme={null}
name: gpt-4o-mini-transcribe
label: GPT-4o Mini Transcribe
input_types:
  - audio/flac
  - audio/mpeg
  - audio/mp4
  - audio/ogg
  - audio/wav
  - audio/webm
```

### Parameter Schema and Overrides

The `parameter_schema` exposed to the frontend is built in two layers:

1. **Base schema**: auto-derived from the model's `Parameters` class via `model_json_schema()`. This lists every adjustable parameter (`temperature`, `max_tokens`, `thinking_enable`, ...) along with its type and the API-wide range.
2. **Per-model overrides**: the YAML's `parameter_overrides` block is merged on top, field by field.

Overrides matter because adjustable ranges are not uniform across an API: every Qwen model accepts `max_tokens`, but each one has a different ceiling. Overrides let a card tighten a range, pin a default, or hide a parameter that doesn't apply.

| Override syntax | Effect |
| - | - |
| `param: { ... }` | Shallow-merge into the base field (e.g. `max_tokens: {maximum: 16384}`) |
| `param: { hidden: true }` | Hide the parameter from the frontend |
| `param: null` | Remove the parameter entirely |

> [!NOTE]
>
> Some adjustments are applied automatically, without an explicit override: chat cards drop `thinking_enable` / `thinking_budget` when `application/x-thinking` is absent from `output_types` and cap `max_tokens` at `output_size`; TTS cards turn the `voices` list into an enum on the `voice` field.

### Retrieve ModelCards

Model card discovery follows the hierarchy: **credential class ⇒ model class ⇒ model cards**. Each credential knows its linked model class for every family (`get_chat_model_classes()`, `get_tts_model_classes()`, `get_asr_model_classes()`, `get_embedding_model_class()`), and each model class loads the YAML card definitions from the `_models/` directory next to its implementation:

```python theme={null}
from agentscope.credential import DashScopeCredential

# Credential class -> model class
model_cls = DashScopeCredential.get_chat_model_class()  # -> DashScopeChatModel

# Model class -> model cards
cards = model_cls.list_models()                          # -> list[ModelCard]
```

In practice, call `list_models()` on either end of the chain. The tabs below show the retrieval for each family:

```python Chat theme={null}
from agentscope.credential import DashScopeCredential
from agentscope.model import AnthropicChatModel

# Via credential class: aggregates all linked chat model classes
cards = DashScopeCredential.list_models()

# Or directly on the model class
cards = AnthropicChatModel.list_models()

for card in cards:
    print(f"{card.name}: context={card.context_size}, inputs={card.input_types}")
```

```python TTS theme={null}
from agentscope.credential import DashScopeCredential
from agentscope.tts import DashScopeTTSModel

# Via credential class: aggregates cards from every linked TTS model class
cards = DashScopeCredential.list_tts_models()

# Or directly on one TTS model class
cards = DashScopeTTSModel.list_models()

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

```python Embedding theme={null}
from agentscope.credential import DashScopeCredential
from agentscope.embedding import OpenAIEmbeddingModel

# Discover the embedding model class from the credential
embed_cls = DashScopeCredential.get_embedding_model_class()
cards = embed_cls.list_models()

# Or directly on the model class
cards = OpenAIEmbeddingModel.list_models()

for card in cards:
    print(f"{card.name}: dimensions={card.dimensions}")
```

```python ASR theme={null}
from agentscope.asr import OpenAIASRModel
from agentscope.credential import OpenAICredential

# Via credential class: aggregates every linked ASR model class
cards = OpenAICredential.list_asr_models()

# Or directly on one ASR model class
cards = OpenAIASRModel.list_models()

for card in cards:
    print(f"{card.name} (realtime={card.realtime}): {card.input_types}")
```

This design allows the frontend to discover available models, their capabilities, and valid parameter ranges, all from a single credential, without any hardcoded provider logic.

### Select an OpenAI API

`OpenAICredential.list_models()` merges cards from `OpenAIChatModel` and
`OpenAIResponseModel`. The same model name can appear twice with different
parameters and capabilities. Identify a choice by both `card.model_class`
and `card.name`, and render that card's `parameter_schema`:

```python Discover OpenAI API choices theme={null}
from agentscope.credential import OpenAICredential

# Each card identifies its API as well as its model name.
for card in OpenAICredential.list_models():
    print(f"{card.model_class}: {card.name}")
```

For direct Python calls, instantiate `OpenAIChatModel` for Chat Completions
or `OpenAIResponseModel` for Responses. In Agent Service, store the selected
card's discriminator in `ChatModelConfig.model_class`. An empty value keeps
legacy default resolution; the standard OpenAI credential defaults to Chat
Completions. An explicit class must be supported by the selected credential.

## Next Steps

> **[LLM](https://docs.agentscope.io/en/versions/2.0.11/building-blocks/model/llm.md)**
>
> Create and call chat models, generate structured output, and add custom providers.

> **[TTS](https://docs.agentscope.io/en/versions/2.0.11/building-blocks/model/tts.md)**
>
> Synthesize speech in standard and realtime modes, and integrate TTS with agents.

> **[ASR](https://docs.agentscope.io/en/versions/2.0.11/building-blocks/model/asr.md)**
>
> Transcribe audio with built-in models or implement a custom provider.

> **[Embedding](https://docs.agentscope.io/en/versions/2.0.11/building-blocks/model/embedding.md)**
>
> Embed text and multimodal content, with built-in batching, retry, and caching.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.