# Model Specs
Model specs are how ReqLLM knows which model to call and what metadata is needed to route the request correctly.
That can be as simple as a registry lookup like `"openai:gpt-4o"`, or as explicit as a full `%LLMDB.Model{}` that carries the provider, model ID, base URL, and any extra routing metadata needed for a model that is not in the registry yet.
This guide covers both paths.
## Start with LLMDB
ReqLLM uses [`llm_db`](https://hex.pm/packages/llm_db) as its model registry. The easiest human-readable reference for that registry is [LLMDB.xyz](https://llmdb.xyz).
Use [LLMDB.xyz](https://llmdb.xyz) when you want to:
- look up the exact provider and model ID to pass to ReqLLM
- inspect current model variants and versioned releases
- confirm whether a date-stamped release ID already exists in the registry
- copy an exact `provider:model` spec instead of guessing
ReqLLM and LLMDB intentionally lean into exact, versioned model IDs when providers publish them. That is why you will often see date-based or version-stamped IDs such as:
- `anthropic:claude-3-5-sonnet-20240620`
- `openai:gpt-4o-mini-2024-07-18`
- `google_vertex:claude-sonnet-4-5@20250929`
That strategy matters for developer experience:
- exact IDs are reproducible and easier to debug
- aliases can still resolve to a current canonical model through LLMDB
- moving from one dated release to another is an explicit choice instead of an accidental drift
If the model is already on [LLMDB.xyz](https://llmdb.xyz), prefer using that exact spec first.
## What A Model Spec Is
A model spec is the complete input ReqLLM uses to resolve a model.
In practice, ReqLLM supports four forms:
### 1. String Specs
The most common path. Strings resolve through LLMDB.
```elixir
"anthropic:claude-haiku-4-5"
"openai:gpt-4o-mini-2024-07-18"
"google_vertex:claude-sonnet-4-5@20250929"
```
### 2. Tuple Specs
Tuples also resolve through LLMDB, but let you keep the provider and model ID split.
```elixir
{:anthropic, "claude-haiku-4-5", max_tokens: 512}
{:openai, id: "gpt-4o"}
```
### 3. `%LLMDB.Model{}`
This is the canonical explicit model contract in ReqLLM.
If you already have a `%LLMDB.Model{}`, ReqLLM uses it directly instead of looking up the model in the registry.
```elixir
model =
LLMDB.Model.new!(%{
provider: :openai,
id: "gpt-6-mini",
base_url: "http://localhost:8000/v1"
})
ReqLLM.generate_text!(model, "Hello")
```
### 4. Plain Maps
ReqLLM accepts plain maps for backwards compatibility and convenience.
They are treated as full model specs and normalized into an enriched `%LLMDB.Model{}`.
```elixir
ReqLLM.generate_text!(
%{provider: :openai, id: "gpt-6-mini", base_url: "http://localhost:8000/v1"},
"Hello"
)
```
The clearer path is to normalize first with `ReqLLM.model!/1`.
## How ReqLLM Resolves Model Specs
ReqLLM has two distinct resolution paths:
### Registry Path
Strings and tuples resolve through LLMDB.
```elixir
{:ok, model} = ReqLLM.model("openai:gpt-4o")
{:ok, model} = ReqLLM.model({:anthropic, "claude-haiku-4-5"})
```
This path is best when:
- the model already exists in LLMDB
- you want aliases and canonical version resolution
- you want shared metadata like pricing, capabilities, and limits
### Full Model Specification Path
`%LLMDB.Model{}` values and plain maps bypass registry lookup. They are self-contained model specs.
This path is best when:
- a new model exists but is not in LLMDB yet
- you are testing a local or proxied deployment
- you need per-model `base_url` metadata
- you are working with a private or experimental model ID
This is the key point: you do not need the model to exist in LLMDB before ReqLLM can use it, as long as you provide a complete enough model spec.
## Recommended Workflow
### Use a string when the model is in LLMDB
```elixir
ReqLLM.generate_text!("openai:gpt-4o", "Hello")
```
### Pin an exact release when reproducibility matters
```elixir
ReqLLM.generate_text!("anthropic:claude-3-5-sonnet-20240620", "Hello")
```
### Use `ReqLLM.model!/1` when the model is not in LLMDB yet
```elixir
model =
ReqLLM.model!(%{
provider: :openai,
id: "gpt-6-mini",
base_url: "http://localhost:8000/v1"
})
ReqLLM.generate_text!(model, "Hello")
```
### Keep the resulting `%LLMDB.Model{}` if you are going to reuse it
```elixir
model =
ReqLLM.model!(%{
provider: :openai,
id: "gpt-6-mini",
base_url: "http://localhost:8000/v1"
})
ReqLLM.generate_text!(model, "Write a haiku")
ReqLLM.stream_text!(model, "Write a poem")
```
## Minimum Required Fields
For the full model specification path, the minimum required fields are:
- `provider`
- `id` or `model`
ReqLLM then enriches and normalizes the spec where possible.
## Common Fields
These are the fields you will use most often when building a full model spec.
### `provider`
The provider atom, such as `:openai`, `:anthropic`, `:google`, `:google_vertex`, `:azure`, or `:openrouter`.
This is required.
### `id`
The ReqLLM model ID.
For most cases this is also the API model ID. This is required unless you provide `model` instead.
### `model`
An alternate way to provide the model ID. ReqLLM normalizes `id` and `model` so either can seed the spec.
### `provider_model_id`
The provider-facing model ID when it should differ from `id`.
This is useful when:
- you want a friendlier local `id`
- you want to preserve an alias in `id` but send a different provider model ID
- a provider needs a specific wire ID that differs from your local identifier
If it can be derived, ReqLLM and LLMDB will fill it in for you.
### `base_url`
Per-model endpoint metadata.
This is especially useful for:
- local OpenAI-compatible servers
- proxies
- Azure resource endpoints
- provider-compatible gateways
### `capabilities`, `limits`, `modalities`, `pricing`, `cost`
Optional metadata that can improve validation, usage reporting, and capability checks.
You do not need to provide all of these just to make a request.
### `extra`
Provider-specific metadata that does not belong in the common top-level fields.
The main advanced cases today are:
- `extra.family` for certain Google Vertex MaaS models
- `extra.wire.protocol` when you need to force a specific OpenAI-compatible wire protocol
## Examples
### Standard Catalog Model
```elixir
ReqLLM.generate_text!("openai:gpt-4o", "Hello")
```
### Exact Dated Release
```elixir
ReqLLM.generate_text!("openai:gpt-4o-mini-2024-07-18", "Hello")
```
### Local OpenAI-Compatible Server
```elixir
model =
ReqLLM.model!(%{
provider: :openai,
id: "qwen3-32b",
base_url: "http://localhost:8000/v1"
})
ReqLLM.generate_text!(model, "Explain supervision trees")
```
### Azure
Azure often benefits from the full model specification path because the Azure resource URL is model metadata.
`deployment` is still a request option.
```elixir
model =
ReqLLM.model!(%{
provider: :azure,
id: "gpt-4o",
base_url: "https://my-resource.openai.azure.com/openai"
})
ReqLLM.generate_text!(
model,
"Hello",
deployment: "my-gpt4-deployment"
)
```
### Google Vertex MaaS
Some Google Vertex MaaS and OpenAI-compatible model IDs need an explicit family hint if the family cannot be inferred from the ID alone.
```elixir
model =
ReqLLM.model!(%{
provider: :google_vertex,
id: "zai-org/glm-4.7-maas",
extra: %{family: "glm"}
})
ReqLLM.generate_text!(model, "Hello")
```
## Advanced: Local `%LLMDB.Model{}`
The canonical advanced path is an explicit `%LLMDB.Model{}`.
If you want full control, build it directly with `LLMDB.Model.new!/1`.
```elixir
model =
LLMDB.Model.new!(%{
provider: :openai,
id: "gpt-6-mini",
provider_model_id: "gpt-6-mini",
base_url: "http://localhost:8000/v1",
capabilities: %{chat: true},
limits: %{context: 200_000, output: 8_192}
})
ReqLLM.generate_text!(model, "Hello")
```
This is useful when:
- you want to construct and store reusable model definitions yourself
- you want a fully explicit contract with no ambiguity about the final struct
- you are integrating ReqLLM into a system that already manages model metadata
Plain maps are still accepted, but conceptually they are convenience input for constructing `%LLMDB.Model{}` values.
## Validation And Errors
ReqLLM intentionally hard-fails early for malformed full model specs.
Common failures include:
- missing `provider`
- missing `id` or `model`
- provider string that does not correspond to a registered provider
- provider-specific routing metadata that cannot be inferred
Provider-specific examples:
- Azure still needs `base_url`
- Google Vertex MaaS models may need `extra.family`
This is an advanced workflow, so explicit errors are preferred over silent fallback behavior.
## Useful Helpers
### Resolve a model spec
```elixir
{:ok, model} = ReqLLM.model("openai:gpt-4o")
model = ReqLLM.model!(%{provider: :openai, id: "gpt-6-mini"})
```
### Browse models in the registry
```elixir
models = LLMDB.models(:openai)
specs = Enum.map(models, &LLMDB.Model.spec/1)
```
### Resolve directly through LLMDB
```elixir
{:ok, model} = LLMDB.model("openai:gpt-4o")
```
## When To Update LLMDB Instead
The full model specification path is the fastest way to use a model that is missing from the registry.
You should still update LLMDB or add registry metadata when you want:
- the model to be discoverable on [LLMDB.xyz](https://llmdb.xyz)
- shared, reusable metadata for the team
- compatibility tooling such as `mix mc`
- richer cost, capability, and limit metadata everywhere
Use the registry for shared catalog quality.
Use full model specs when you need to move immediately.
