# Configure models and capabilities

Map Dicto catalog identities to provider models and verify each capability explicitly.

Dicto configures model catalogs in server YAML under `ai`. The backend keeps
provider credentials; clients receive the appropriate authorized catalog.

| Field | Meaning |
| --- | --- |
| `id` | Stable Dicto catalog ID used by the app |
| `name` | Human-readable model name |
| `provider_model` | Model string sent to the provider or gateway alias |
| `base_url` | Complete provider API root, including `/v1` or other prefix |
| `api_key` | Credential for that endpoint, usually an environment reference |
| `is_default` | Default selection in that capability's catalog |

Model-level `base_url` and `api_key` override capability defaults. References
such as `"${CHAT_API_KEY}"` must be complete server YAML string values; do not
assume a global `OPENAI_API_KEY` implicitly configures every service. Desktop
app YAML does not use the server's environment-substitution mechanism.

## Separate the capabilities

- `transcription`: audio upload to `/audio/transcriptions`; verify real audio
  and the desired response format.
- `chat`: text-generation requests; verify the APIs, streaming, tools and output
  formats the consuming feature actually uses.
- `embeddings` and `reranking`: independent optional model/services for selected
  retrieval features, with their own model/dimension compatibility.
- `realtime_speech` and optional transcription realtime/diarization: independent
  contracts, not implied by a successful batch transcription.

The [reference file](/examples/reference/server/server.yaml) uses gateway alias
`whisper` for transcription and `llm-default` for chat. The
[route file](/examples/reference/llm-server/models.json) maps them to upstream
models. Change all relevant layers together when replacing a model.

Do not enable `supports_token_logprobs`, realtime or diarization flags merely
because an endpoint calls itself OpenAI-compatible. The portable Whisper example
does not include the maintained deployment's token-logprob patch. Keep optional
reasoning efforts/summaries absent unless the selected model/provider supports
them. The [generated server schema](/schemas/server.schema.json) describes the
exported configuration contract; the deployed server performs final validation.