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.

Aliases are one of three ways to reference a model. See Model Naming for when to use bare (gpt-5-mini) vs prefixed (openai/gpt-5-mini) vs an alias.

{
  "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:

# every file needs to know the Azure deployment name
model = "my-eastus-gpt-4o-deployment"

After:

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:

{"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 the gateway looks up <name> in model_aliases. If there is an entry, the gateway checks the mapped provider/model against models_allowed. If the check passes, the gateway dispatches it.
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.

Enforcement

Aliases do not go around models_allowed. The allowlist judges the model that the alias resolves to, never the name that the caller typed. It accepts the two spellings of that model: an entry of gpt-5-mini and an entry of openai/gpt-5-mini match the same resolved model. Write the form that your team reads.

If models_allowed: ["gpt-5-mini", "claude-haiku-4-5-20251001"] and an alias maps to openai/o3, the gateway refuses a request that uses the alias with model_not_allowed. The refusal names o3, the resolved model, and it names the alias. The operator can see which side to correct.

This matters for security: do not grant a model through an alias that you would not grant directly.

Policy rules judge the resolved model in the same way. An alias that points to a denied model is blocked.

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 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 the team has to look up. 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).