Skip to main content

​
The short version

Put an exact catalog id in model and the gateway preserves that logical model across provider failover while your plan allows it. Use auto for plan-aware cross-model routing. Entries marked optimized are compatibility ids whose physical model may vary.

​
What model accepts

Resolution runs in a fixed order and the first match wins:
1

An exact catalog id

@sdn/glm-5.3 for an open-weight model, gpt-6.1-sol for a closed-weight one. This is the public id GET /v1/models returns and what you should pin in production. The older spellings (sdn-glm-5.3 and the bare glm-5.3) resolve to the same model, permanently. Casing does not matter on any of these paths.
2

A published alias

Each entry’s aliases array in the catalog. Aliases are part of the contract; read them from the endpoint rather than guessing.
3

A short family handle

A small set of one-word handles resolve to that family’s current default — glm, kimi, qwen, deepseek, gpt-oss.
4

A known foreign stock name

A finite list of ids that SDKs and agents commonly ship hard-coded — gpt-4o, claude-sonnet-4-5, o3, codex, gemini-2.5-pro, mistral-large and a handful of others — each mapped to a catalog model. See below.
5

A vendor/model string, retried on its basename

OpenRouter-style ids like openai/gpt-4o are retried as gpt-4o through the same ladder above.
Anything that survives all of them is a 404 — an unknown model fails closed rather than silently becoming something else.

​
Foreign model ids

An agent arriving with gpt-4o or claude-sonnet-4-5 baked into its config works without being reconfigured. This is a finite, explicit compatibility list, not a pattern match: invented or future ids (gpt-7, claude-opus-9) are not silently accepted. Two consequences worth knowing:
  • The response echoes your string. Send gpt-4o and both the response body and the sideren-model header say gpt-4o, because strict clients round-trip that id. Physical placement is private; the catalog’s delivery field tells you whether the public id is exact or optimized.
  • The mapping can move. These handles point at whichever catalog model is the right landing spot today. Treat them as a compatibility shim for tools you cannot configure — never as a production pin. Pin catalog ids in anything you own.

​
Omitting the model, and auto

Leave model out, or set it to auto, and you are telling the gateway that the choice is its to make. Both do the same thing: they resolve to the platform default and additionally unlock the router’s automatic tier, which may serve an equivalent model when it can do the work.
Use it for high-volume work where “a good answer” is the requirement. Do not use it where you need a specific model’s exact behavior — name the model instead. A named model is never silently upgraded to a more expensive one. One exception inside agent loops: a request that carries tools resolves auto once to a stable workhorse model and stays on it for the whole run, so a tool loop doesn’t change models mid-conversation.

​
Reading back what served you

Two places, and they answer different questions: They remain provider-neutral and normally match. Neither exposes an upstream account or physical fallback; use the dashboard’s request history for that evidence.

​
Picking a model deliberately

  • Pin an id whose delivery is exact for evals, structured extraction, or a golden-path step. Catalog rows marked optimized are served by a comparable model the gateway chooses.
  • Check capabilities before you send. capabilities.vision, capabilities.tools and supported_parameters on the catalog entry tell you whether a model will accept what you are about to send. A capability a model cannot guarantee returns 422 rather than being quietly dropped — see Errors.
  • Match the tier to the step. Agent loops are mostly cheap steps and a few hard ones; the catalog is grouped by tier so you can put the workhorse on the loop and a frontier model on the step that needs it. Each request takes credits for the model that served it, so a lighter model on the hot path is directly more requests.