Skip to content

Choosing a model

The model field of a request decides whether you name a model or let Prism choose one. This applies to Chat Completions, Responses, Anthropic Messages, Gemini (model in the path) and Ollama chat. Embeddings and rerank follow their own rules, described on Ingress dialects.

model What Prism does
auto, or empty Chooses a model with the request’s strategy (default balanced)
cheap, fast Chooses with that strategy
smart Chooses with the quality strategy and at least the strong quality tier
local Chooses among local models only; never sends the request to a cloud provider
openai/auto, google/fast, <provider>/<selector> Chooses among one provider’s models
triage, reasoning, cheap-toolcall Built-in roles, active once you list models for them in [routing.role_aliases]
reasoning-max The reasoning role at the maximum reasoning effort
A name you add to [routing.role_aliases] Your role: its listed models, in order
prism/auto, prism/strong, prism/frontier, prism/reasoning, prism/reasoning-max, prism/private Policy models; /v1/models lists the ones available now
provider::model, for example openrouter::anthropic/claude-sonnet-4.5 That model at that provider (any account of it). Other providers are tried only when failover is allowed, see below
A model id, for example gpt-5-mini or anthropic/claude-sonnet-4.5 That model at any provider that serves it

balanced, quality and private are strategy names, not model names. "model": "balanced" is read as a model id and fails with 400 no provider has exact model_id balanced. An unknown prism/... name is a 400.

Lists:

  • GET /v1/models lists provider models as provider::model, role aliases you configured, and prism/* policy models. It does not list auto, cheap, fast, smart, local.
  • GET /prism/models lists every catalog entry with its candidate_id (provider/model), quality tier, limits, prices, health, and whether automatic routing may pick it.

With the default configuration ([v2] on), a request Prism routes itself orders the eligible models by strategy:

Strategy Order
balanced (default) The strongest cloud model at or above the turn’s quality-tier floor: the one with the highest Epoch Capabilities Index in the model class catalog, price deciding only between equals. The floor is frontier when the request offers tools (an agent step) or rates as complex, good otherwise. If no cloud model reaches the floor, the highest tier below it comes next, then local models. A model with no known tier never counts as reaching the floor
quality Highest quality tier first; inside it the strongest model by Epoch ECI, price only between equals
cheap Local models first, then the cheapest cloud model
fast Lowest observed latency first, then cheapest
private Local models only

auto without a strategy behaves as balanced. A request marked private or local uses local models only, whatever the strategy.

If the first model fails with a retryable error, Prism tries the next one in the order.

Where Scope
model: "cheap" / "fast" / "smart" / "local" One request
X-Prism-Strategy: balanced|quality|cheap|fast|private header with model: "auto" One request. smart is read as quality, local as private; an unknown value as balanced
/prism strategy cheap in chat, with X-Prism-Session One conversation; see In-chat commands
Console → Routing, or set_default_strategy in the control API The whole installation
[v2.orchestration] default_strategy in config.toml The whole installation, when nothing above is set

A concrete model in the request always wins over any strategy.

Header Effect
X-Prism-Strategy Strategy for this request
X-Prism-Session Names the conversation. Prism keeps a conversation on the model and account that hold its prompt cache while that is still allowed and cheaper than switching, and applies session controls. Not a hard lock: health, capability and limits still apply
X-Prism-App Names the agent for reports. A name you map in [routing.app_profiles] also selects that routing profile
X-Prism-Profile Selects a routing profile ([profiles.<name>]) directly
X-Prism-Allow-Provider-Failover: true Lets a provider::model request go to another provider that serves the same model. Default: [routing] allow_provider_failover (false)

A provider::model request names the provider whose price and account you accept. By default Prism does not send it to another provider: if that provider cannot serve, you get its refusal, and the error may carry a prism_switch_offer that names another provider of the same model. A second account of the same subscription provider counts as the same provider and can take over. Allow other providers per request with X-Prism-Allow-Provider-Failover: true, or for the installation with [routing] allow_provider_failover = true.

The X-Prism-Provider response header always names the provider that served.

Chat Completions and Responses requests may carry a prism object with routing requirements. Prism checks it before routing and removes it before forwarding.

{
"model": "auto",
"prism": {
"version": "intent-v1",
"role": "reasoning",
"quality": "strong",
"effort": "adaptive",
"locality": "prefer-local",
"max_cost_usd": 0.25,
"max_latency_ms": 1500,
"required_capabilities": ["tools", "json"]
}
}
Field Values
version intent-v1 (required)
role auto, reasoning, triage, cheap-toolcall
quality adaptive, strong, frontier
effort adaptive, none, minimal, low, medium, high, xhigh, max
locality any, prefer-local, local-only, cloud-only
max_cost_usd, max_latency_ms Upper bounds for the request
required_capabilities Up to 32 of: tools, json, structured-output, vision, streaming, responses, reasoning, cache:explicit, cache:implicit, backend:<name> (aggregator backend)
  • The encoded object may be at most 4096 bytes. Unknown or duplicate fields, wrong types and invalid values are a 400 invalid_request that names the field, for example invalid routing intent prism.bogus: unknown field.
  • A capability name Prism does not know leaves no eligible model: 503 no_eligible_executor, as does a capability every candidate is stated not to have. A capability nobody has stated for a model is not a “no”: that model stays a candidate and is tried after the models on which the capability is confirmed. Prism learns tools, json, vision, streaming and responses from traffic, a background check, the provider, your settings, the public model table and its built-in rule, in that order, and the models dialog of a connection under AI providers shows each flag as yes, no or unknown with where it came from. Only an explicit “no” — from the provider, your settings or traffic — removes a model from the request.
  • local-only (like model: "local" and prism/private) cannot be weakened by a default, a budget rule or failover.
  • Embeddings, rerank, System One and the file, image and audio endpoints do not read this object.