model field accepts three forms. Each one tells the gateway a different amount about where the request goes.
A fourth kind of name, an alias, is a name a routing policy maps to one of the forms above. See Model Aliases.
Resolution order
The gateway reads themodel string once, in this order. The first step that matches decides.
- Alias. If the routing policy maps the exact string to a target, the target replaces it. The target is then read with the same rules as a request, so an alias can point at any of the three forms.
- Instance handle. If the text before the first
/is a routing handle on one of the key’s providers, the request is pinned to that provider instance. The rest of the string is the model id. - Provider family. If the text before the first
/is a provider family the gateway knows, the request goes to a provider of that kind. The rest of the string is the model id, including any further/. - Bare model. Otherwise the whole string is the model id, slashes included, and the gateway infers the provider from it.
openai/gpt-5-mini as a model name.
Provider families
openai, anthropic, azure, bedrock, vertex, gemini, xai, groq, cerebras, deepseek, voyage, elevenlabs, cloudflare, custom, openai_codex.
The alternative spellings that SDKs emit are accepted too: azure_openai, aws_bedrock, vertex_ai, google_vertex, google_gemini. The family is case-insensitive, so OpenAI/gpt-5-mini works.
A family names a kind of provider, not one instance. If the key reaches two Anthropic providers, anthropic/claude-sonnet-5 matches both and the first one in the key’s provider order serves the request. The others stay available for failover. Use an instance handle to choose one.
The provider order is the order in the key’s routing policy. A key with no policy orders its providers by the global fallback priority set on each provider, then by creation date.
How the gateway infers the provider for a bare model
For a bare model name the gateway tries four steps and stops at the first one that leaves at least one provider:- Providers that declare the model. A custom provider lists the models it serves, and a hosted provider ships a catalog. This is what makes a declared model routable without a prefix.
- The vendor in the name. A short built-in table maps a prefix to the vendor that originated it. This is the safety net for a model newer than the shipped catalog.
- Providers with no model list. A provider with no model list cannot be ruled out by a model it does not list.
- A key with one provider. With one provider there is no choice to make, so the gateway forwards any model name to it.
model_not_recognized.
The vendor table in step 2:
Bedrock and Vertex are not in the table. Write
bedrock/anthropic.claude-… or vertex/…, or use an alias, to reach a Claude or Gemini model through them.
Model ids that contain a slash
A model id can contain a/ of its own, which is normal for self-hosted servers and proxies: stealth/ox-alpha, meta-llama/Llama-3-70B. The gateway reads the first segment as a prefix only when it is a routing handle or a provider family. Once you declare stealth/ox-alpha on the provider that serves it, "model": "stealth/ox-alpha" works as written.
One case still needs a prefix. A model whose first segment spells a provider family, for example openai/my-finetune on a self-hosted server, is read as the openai family. Write custom/openai/my-finetune instead.
Instance handles
A routing handle is a name you give to one model provider. Set it on the provider in Settings → Model Providers. It is unique inside your organization, soeurope/claude-sonnet-5 names the same provider from every key that reaches it.
Use a handle when you run more than one provider of the same kind and want to choose between them in the request. For example, a European and a United States Anthropic account.
Rules for a handle:
- Lowercase. It starts with a letter or a number, then letters, numbers, hyphens and underscores, up to 32 characters.
- It cannot be a provider family name, or one of the reserved words
azure_openai,aws_bedrock,vertex,google_vertex,google_gemini,cloudflare,mp. - Renaming a handle is a breaking change for every caller that uses it. Requests naming the old handle stop reaching that provider immediately.
model_provider_not_bound naming the handle. No other provider serves it in its place.
GET /v1/models lists the models of a provider that has a handle under the handle-qualified name, so europe/claude-sonnet-5 appears rather than claude-sonnet-5. See API: GET /v1/models.
Declaring the models a provider serves
Hosted providers already declare their models, sogpt-5-mini and claude-sonnet-5 route without setup.
For a Custom (OpenAI-compatible) provider, add the models under Custom models on the provider. That is what lets a caller send the bare model name instead of custom/ in front of it, and what puts the model in GET /v1/models.
A key with one provider does not need this. Every model name is forwarded to that provider.
When a name does not resolve
Every refusal is a JSON error witherror.code, and the HTTP status is fixed per code.
model_provider_not_bound and model_not_recognized list the prefixes the key accepts, so the caller can correct the request from the message. The list is capped at ten names and is also in error.meta.options.
models_allowed plays no part in choosing a provider. It judges the model the request resolves to, in both spellings: an entry of gpt-5-mini and an entry of openai/gpt-5-mini allow the same model.
Also check: Troubleshooting for the full error index.
Choosing a form
1
One provider on the key
Use the bare model name.
2
Several providers, different models
Use the bare model name. Each provider declares its own models, so the name is enough.
3
Several providers of the same kind
Give each one a routing handle and use it:
europe/claude-sonnet-5.4
A stable name you can repoint later
Use an alias in the routing policy. See Model Aliases.
5
Failover between providers
Name a model that more than one provider on the key serves. The gateway carries the same model name to the next provider in the chain. See Fallback Chains.