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 values
Section titled “Model values”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/modelslists provider models asprovider::model, role aliases you configured, andprism/*policy models. It does not listauto,cheap,fast,smart,local.GET /prism/modelslists every catalog entry with itscandidate_id(provider/model), quality tier, limits, prices, health, and whether automatic routing may pick it.
Strategies
Section titled “Strategies”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.
Setting the strategy
Section titled “Setting the strategy”| 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.
Request headers
Section titled “Request headers”| 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) |
Pinned provider
Section titled “Pinned provider”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.
Routing intent
Section titled “Routing intent”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_requestthat names the field, for exampleinvalid 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 learnstools,json,vision,streamingandresponsesfrom 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(likemodel: "local"andprism/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.