Model aliases¶

You should always send an alias in the model field. The gateway translates the alias into a real OpenRouter model ID using the frozen registry in frozen-v3/config/models.yaml. The real IDs are not part of the public contract and may change without breaking your integration.

The four aliases¶

Alias	Real model	Role	When to use it
`smart-router`	(chosen by policy)	Auto-routing	The default. Use this unless you have a specific reason.
`smart-router-flash`	`deepseek/deepseek-v4-flash-0731`	Default worker	When you want the cheap worker, no matter what.
`smart-router-pro`	`deepseek/deepseek-v4-pro-0813`	Senior solver	When you know the task is hard.
`smart-router-free`	`nvidia/nemotron-3-ultra-550b-a55b:free`	Scout / critic	Only for public, non-sensitive work.

The emergency fallback model, z-ai/glm-5.2, is not exposed as an alias. The gateway only uses it internally if a Pro call fails end to end.

Forcing a tier without changing `model`¶

If your client cannot set the model field dynamically, use the header equivalents:

Header	Effect
`X-Pro: true`	Same as `smart-router-pro`.
`X-Scout: true`	Run Scout first; the gateway then forwards to Pro or Flash based on the Scout's recommendation.

Both still respect the privacy gate and the budget policy.

Why aliases instead of real IDs?¶

There are four reasons:

Decoupling. A OpenRouter ID can change when a provider rotates endpoints, retires a model, or moves traffic. The alias layer lets the gateway absorb that change without breaking your client.
Privilege separation. Real OpenRouter IDs may correspond to models with different data-handling properties. The alias keeps you from accidentally picking the wrong one for a sensitive task.
Routing flexibility. The gateway can substitute an equivalent model in a routing decision (e.g. demote Pro to Flash when the model is unhealthy) and the alias stays meaningful to you.
Audit clarity. Routing logs record the alias and the chosen real ID side by side. You can grep for model_alias=smart-router-pro without knowing which OpenRouter model that was at the time.

How to discover what was actually used¶

In the response body, the model field contains the real OpenRouter ID:

{ "model": "deepseek/deepseek-v4-flash-0731", "choices": […] }

In the structured routing log, look for:

{
  "decision": {"action": "ROUTE", "model": "deepseek_v4_flash", "cause": "score_flash"}
}

The model here is the internal alias key, not the OpenRouter ID. They map 1:1 today but they are different namespaces.

What happens when an alias changes?¶

Because the model registry is part of the architecture freeze, an alias can only be re-pointed by issuing a new release. The freeze ID is checked at startup; a mismatch prevents the gateway from booting.

If you want to use a new model that the current registry does not cover, follow the release process at docs-internal/development/release-process.md or the routing change policy at docs-internal/development/routing-change-policy.md (operator-only).

Quick reference¶

# Default
curl -sS -H "Authorization: Bearer $KEY" \
  -d '{"model":"smart-router","messages":[...]}' "$URL/v1/chat/completions"

# Force Pro
curl -sS -H "Authorization: Bearer $KEY" \
  -H "X-Pro: true" \
  -d '{"model":"smart-router","messages":[...]}' "$URL/v1/chat/completions"

# Force Flash
curl -sS -H "Authorization: Bearer $KEY" \
  -d '{"model":"smart-router-flash","messages":[...]}' "$URL/v1/chat/completions"

# Force Free (rejected if sensitive)
curl -sS -H "Authorization: Bearer $KEY" \
  -d '{"model":"smart-router-free","messages":[{"role":"user","content":"summarize this public doc"}],"metadata":{"sensitive":false}}' "$URL/v1/chat/completions"