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

# Model Aliases

> Per-VK redirects from client-facing model names to specific provider/model/deployment combinations.

A model alias is a per-VK redirect. The client sends `model: "foo"`; the VK's `model_aliases` map turns it into `provider/model/deployment` at dispatch time.

<Info>Aliases are one of three ways to reference a model. See [Model Naming](/docs/ai-gateway/model-naming) for when to use bare (`gpt-5-mini`) vs prefixed (`openai/gpt-5-mini`) vs an alias.</Info>

```json theme={null}
{
  "model_aliases": {
    "gpt-4o":       "azure/my-eastus-deployment",
    "claude":       "anthropic/claude-haiku-4-5-20251001",
    "big-model":    "openai/gpt-5",
    "fast":         "gemini/gemini-2.5-flash"
  }
}
```

## Two main use cases

### 1. Decouple client code from provider specifics

An OpenAI-SDK codebase shouldn't need to know about Azure deployment names, Bedrock inference profile ARNs, or specific Anthropic model versions. Aliases move that mapping to the VK.

Before:

```python theme={null}
# every file needs to know the Azure deployment name
model = "my-eastus-gpt-4o-deployment"
```

After:

```python theme={null}
model = "gpt-4o"   # the VK maps this to the right Azure deployment
```

Changing the deployment, because you scaled up, moved region, or pinned a new model version, is a one-click edit on the VK. No code change, no rollout.

### 2. Swap providers without client changes

Operating under the alias `claude` pointing at `anthropic/claude-haiku-4-5-20251001`. Anthropic has a regional outage, or you want to test Bedrock for cost reasons. Change the alias:

```json theme={null}
{"claude": "bedrock/us.anthropic.claude-haiku-4-5-20251001"}
```

Every client using `model: "claude"` now hits Bedrock. Switch back in one edit. Canary traffic by minting a second VK with the new alias while the primary stays on Anthropic.

## Resolution rules

Given a request with `model: "<name>"`:

1. If `<name>` has a `/` in it (explicit `provider/model` form), **aliases are bypassed** and the gateway routes directly to that provider, subject to `models_allowed` and the VK's `providers[]` list.
2. Otherwise, `<name>` is looked up in `model_aliases`. If found, the mapped `provider/model` is used.
3. If not found in aliases, the gateway checks `models_allowed`. If the model is allowed, it's dispatched to the VK's primary provider.
4. If none of the above, returns `403 model_not_allowed`.

## Aliases always win over explicit form: if both are defined

If the alias map has an entry for `gpt-4o` **and** the client sends `model: "gpt-4o"`, the alias is applied. If the client sends `model: "openai/gpt-4o"` explicitly, the alias is bypassed (step 1).

This lets you have an `openai/` namespace that addresses OpenAI directly for tests or debugging while the alias `gpt-4o` redirects to Azure for production traffic.

## `:fallback` suffix (advanced)

Optional suffix that picks a different model when a fallback provider is used:

```json theme={null}
{
  "model_aliases": {
    "coding-small":            "openai/gpt-5-mini",
    "coding-small:fallback":   "anthropic/claude-haiku-4-5-20251001"
  }
}
```

If the primary (OpenAI) fails and fallback kicks in, the gateway uses `claude-haiku-4-5-20251001` against Anthropic. Without `:fallback`, it would try the same model name (`gpt-5-mini`) which might not exist on Anthropic.

## Enforcement

Aliases do not bypass `models_allowed`. If `models_allowed: ["gpt-5-mini", "claude-haiku-4-5-20251001"]` and an alias maps to `openai/o3`, a request using the alias returns `403 model_not_allowed`, the resolved model fails the allowlist.

This matters for security: don't grant a model via aliases that you wouldn't grant explicitly.

## Discovery via `/v1/models`

`GET /v1/models` returns three deduplicated + stable-sorted groups: **(1) alias names**, **(2) `models_allowed` entries (globs included, shown verbatim)**, and **(3) provider-type shortcuts** (`openai/*`, `anthropic/*`, `bedrock/*`, `azure/*`, `vertex/*`, `gemini/*`, one per provider bound on the VK). CLIs that auto-configure completion (Codex, Cursor, `openai models list`) consume the whole list uniformly.

Each entry carries an `owned_by` field indicating the resolved provider, so UIs can render "gpt-4o (Azure)" vs "gpt-4o (OpenAI)" when both are present across different VKs.

See [API: `GET /v1/models`](/docs/ai-gateway/api/models) for the full response shape.

## Trace attributes

* `langwatch.model`, the final resolved model dispatched to the provider (post alias).
* `langwatch.model_source`, how it was resolved: `alias` (client sent an alias that mapped), `explicit_slash` (client sent `provider/model`), or `implicit` (client sent a bare name the gateway mapped via defaults).

Filter the LangWatch Messages view by `model_source="alias"` to see "which requests benefited from the VK's alias table today"; filter by `model` to count Azure vs OpenAI dispatches.

## When NOT to use aliases

* Small projects with one provider and one model, just use the provider's native model name.
* When the alias becomes another layer of indirection nobody remembers. Keep alias names close to the provider-native names if the redirect is simple.

Use aliases where the indirection pays for itself (vendor abstraction, migration primitives, canary testing).