Model Naming

How to name a model in a request, and which provider the gateway sends it to.

The model field of a request accepts four kinds of name. The gateway reads them in one fixed order and the first one that matches decides which provider serves the request.

Model name

"model": "gpt-5-mini". Goes to the bound provider that serves that model.

Provider type

"model": "openai/gpt-5-mini". Goes to a provider of that type.

Routing handle

"model": "europe/claude-sonnet-5". Goes to that exact provider, when the key can reach it.

Alias

"model": "coding-small". A per-key redirect. See Model Aliases.

Resolution order

For every request the gateway reads the model string once, in this order:

1. Alias. If the virtual key defines an alias with that exact name, the alias decides. Nothing after this step runs.
2. Routing handle. If the text before the first / is a routing handle on one of the organization’s providers, the request goes to that provider, and the rest of the string is the model name. The key still has to reach that provider; if it does not, the request is refused with model_provider_not_bound.
3. Provider type. If the text before the first / is a provider type (openai, anthropic, custom, and the rest of the list under Provider types), the request goes to a provider of that type. Everything after the first / is the model name, including any further /.
4. Declared models. Otherwise the whole string is a model name. It is matched against the models each bound provider declares: the custom models you configured on the provider, the model ids of its deployment mapping, and, for the hosted providers, the model catalog LangWatch ships.
5. Model name pattern. If no provider declares the model, a short built-in table maps a name to the vendor that originated it: gpt-… to OpenAI, claude-… to Anthropic, gemini-… to Google. This is the safety net for a model newer than the shipped catalog.
6. Providers that declared nothing. A provider that has not listed the models it serves cannot be ruled out by a model missing from its list, so those providers stay candidates.
7. A key with one provider. One provider is one door, not a choice between vendors, so the request goes to it whatever it declared. This step is what keeps a key working when its provider serves more than it lists.

If none of that places the model, the request is refused with model_not_recognized, and the message lists the prefixes the key accepts.

The examples below read the order above from the top, so each one assumes no earlier step matched. A name that another provider declares, or a first segment that is also a routing handle, is decided by whichever step comes first.

Request model	Where it goes
gpt-5-mini	The bound provider that declares gpt-5-mini, otherwise the bound OpenAI provider
openai/gpt-5-mini	A bound OpenAI provider, model gpt-5-mini
europe/claude-sonnet-5	The reachable provider whose routing handle is europe
stealth/ox-alpha	The provider that declares the model stealth/ox-alpha, when stealth is not a routing handle
custom/stealth/ox-alpha	A bound custom provider, model stealth/ox-alpha
coding-small	Wherever the key’s alias points

The provider prefix is removed before the request leaves, so an upstream never receives openai/gpt-5-mini as a model name.

Model names 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 only reads the first segment as a prefix when it is a provider type or a routing handle. So once you declare stealth/ox-alpha on the provider that serves it, "model": "stealth/ox-alpha" works as written. custom/stealth/ox-alpha also works and is unambiguous.

One case still needs the prefix: a model whose first segment happens to spell a provider type, such as openai/my-finetune on a self-hosted server. The gateway reads openai as the provider type, so write custom/openai/my-finetune instead.

Provider types

openai, anthropic, azure, bedrock, vertex, gemini, deepseek, xai, groq, cerebras, voyage, elevenlabs, custom.

The alternative spellings that SDKs emit are accepted too: azure_openai, aws_bedrock, vertex_ai, google_vertex, google_gemini.

A provider type names a KIND of provider, not one of them. If a key has two Anthropic providers, anthropic/claude-sonnet-5 matches both, and the first one in the key’s order serves the request, as set out under Which provider answers first. Use a routing handle to choose.

Routing 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, so europe/claude-sonnet-5 names the same provider whichever key sends it. A key that cannot reach that provider is refused with model_provider_not_bound rather than served by another one.

Use one when you run more than one provider of the same type and you want to choose between them in the request, for example a European and a United States Anthropic account.

Rules:

• Lowercase, starting with a letter or a number, then letters, numbers, hyphens and underscores. Up to 32 characters.
• It cannot be a provider type, because the gateway would not be able to tell the two apart.
• Renaming a handle is a breaking change for anyone using it: requests naming the old handle stop reaching that provider immediately.

The virtual key drawer shows, for each provider the key can reach, the names that reach it and which provider answers a bare provider type.

GET /v1/models lists a provider that has a handle under the handle-qualified name, so europe/claude-sonnet-5 appears rather than claude-sonnet-5. That is the name that reaches that exact provider, and it is what keeps two providers of the same type apart in the list. The owned_by field stays the provider type, so a model picker still groups by vendor.

Which provider answers first

When a name matches more than one provider, the key’s own order decides, and the rest stay available for failover:

1. The order of the key’s routing policy, when it has one.
2. Otherwise the global fallback priority set on each provider.
3. Otherwise the order the providers were created.

Declaring the models a provider serves

Hosted providers already declare their models, so gpt-5-mini and claude-sonnet-5 route without any setup.

For a Custom (OpenAI-compatible) provider, a self-hosted vLLM, a LiteLLM proxy or any other OpenAI-compatible endpoint, add the models under Custom models on the provider. That is what lets a caller name the model directly instead of writing custom/ in front of it, and it is what puts the model in GET /v1/models.

A key with only one provider does not need this: with one provider there is nothing to choose between, so any model name is forwarded to it.

GET /v1/models also lists models discovered by asking the provider’s own endpoint. Discovery lists a model, but it does not declare it, so it does not tell the gateway which provider owns the bare name. The name can still reach the provider through the later steps of the resolution order, for example when that provider declares no models at all, or when the key has only one provider. On a key with several providers it is not certain: another provider that declares the name takes it first. Declare the model, or name the provider in the request.

Errors

model_provider_not_bound means the request named a provider type or a routing handle that this key cannot reach.

{
  "error": {
    "code": "model_provider_not_bound",
    "message": "The \"bedrock\" provider is not reachable from this key's scope, so no credential is configured for it. This key reaches \"anthropic\", \"openai\", \"europe\". Ask the key's owner to add the provider, or send the request to one of those."
  }
}

model_not_recognized means the request named a model that no bound provider serves.

{
  "error": {
    "code": "model_not_recognized",
    "message": "No provider on this key serves the model \"private-build\". This key reaches \"anthropic\", \"openai\". Name the provider in the model string, or declare the model on the provider that serves it."
  }
}

Both list what the key can reach, so the request can be corrected without reading this page. The list is capped at ten names.

models_allowed is a separate thing

The models allowlist on a virtual key decides what a key is ALLOWED to call. It plays no part in choosing a provider. A model can be declared on a provider and still be refused by the allowlist, and the refusal is model_not_allowed.

Choosing a form

1. One provider on the key

   Use the model name. Nothing else is needed.

2. Several providers, different models

   Use the model name. Each provider declares its own models, so the name is enough.

3. Several providers of the same type

   Give each one a routing handle and use it: europe/claude-sonnet-5.

4. A stable name you want to repoint later

   Use an alias. Edit the key once and no caller changes. See Model Aliases.

5. Failover between providers

   Name a model that more than one bound provider serves. The gateway carries the same model name to the next provider in the chain. See Fallback Chains.