> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# 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.

<CardGroup cols={2}>
  <Card title="Model name" icon="circle-check">
    `"model": "gpt-5-mini"`. Goes to the bound provider that serves that model.
  </Card>

  <Card title="Provider type" icon="slash">
    `"model": "openai/gpt-5-mini"`. Goes to a provider of that type.
  </Card>

  <Card title="Routing handle" icon="key">
    `"model": "europe/claude-sonnet-5"`. Goes to that exact provider, when the key can reach it.
  </Card>

  <Card title="Alias" icon="arrow-right-arrow-left">
    `"model": "coding-small"`. A per-key redirect. See [Model Aliases](/docs/ai-gateway/model-aliases).
  </Card>
</CardGroup>

## 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](#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](#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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

<Steps>
  <Step title="One provider on the key">
    Use the model name. Nothing else is needed.
  </Step>

  <Step title="Several providers, different models">
    Use the model name. Each provider declares its own models, so the name is enough.
  </Step>

  <Step title="Several providers of the same type">
    Give each one a routing handle and use it: `europe/claude-sonnet-5`.
  </Step>

  <Step title="A stable name you want to repoint later">
    Use an alias. Edit the key once and no caller changes. See [Model Aliases](/docs/ai-gateway/model-aliases).
  </Step>

  <Step title="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](/docs/ai-gateway/providers/fallback-chains).
  </Step>
</Steps>