---
title: Model aliases
description: Map your own model names to any catalog model, per API key — point your client once and switch the real model from the dashboard.
---

# Model aliases

A **model alias** is a name *you* choose that points at any model in the CrossModel catalog. Aliases are configured per API key, so you can give a client a stable model name once and re-point it to a different real model whenever you like — without touching the client.

This is what the name CrossModel is about: you call your own name, and we route it across to the model you picked.

## Why use them

Many tools hard-code the model name they send (for example coding assistants that always request a fixed `claude-*` id). With an alias you can:

- Point a client at CrossModel **once** (just the base URL + key), then switch the underlying model from the dashboard.
- Give every project a stable name like `cross-model-basic` / `cross-model-pro` and decide later what each maps to.
- Remap a hard-coded model name a client insists on sending to whatever you actually want to run.

## How resolution works

When a request arrives, the gateway resolves the requested model name against the key's aliases **before** routing and billing:

1. **Exact match** — an alias whose name equals the requested model wins.
2. **Longest prefix match** — among prefix aliases whose name is a prefix of the requested model, the longest one wins.
3. **Passthrough** — if nothing matches, the original name is used unchanged.

Once resolved, the request is routed and billed exactly as if you had sent the real model id. Aliases never change pricing — you pay for the real model that runs.

<Callout type="info">
  Aliases take **priority** over real model names. If you name an alias the same as a real catalog id, the alias wins — which is exactly what lets you remap a name a client hard-codes.
</Callout>

### Exact vs. prefix

- **Exact** — `cross-model-basic` → `deepseek/deepseek-chat`. Only a request for `cross-model-basic` matches.
- **Prefix** — `claude-opus` → `anthropic/claude-opus-4-8` (prefix). Requests for `claude-opus-4-8`, `claude-opus-4-9`, … all match, so a client that bumps its version string keeps working without you editing the alias.

## Configuring aliases

Open the **API Keys** page in the console, click the aliases button on a key, and add rows of *alias → target model*. The target picker searches your available models. A built-in test box lets you type a model name and see exactly which real model it resolves to.

Alias names must be lowercase and may use letters, digits, and `. _ : / -` (up to 64 characters). Each key allows up to 20 aliases.

Changes take effect within about a minute (the gateway briefly caches key data).

## Listing models

`GET /v1/models` returns your aliases (each with a `root` field pointing at the real model id and that model's capabilities) **followed by** the full catalog. Real model names remain callable alongside your aliases, so tools that read the model list see both.

```jsonc
{
  "id": "cross-model-basic",
  "object": "model",
  "root": "deepseek/deepseek-chat",   // the real model this alias resolves to
  "context_length": 65536,
  "architecture": { "input_modalities": ["text"], "output_modalities": ["text"] }
}
```

## Using an alias

Once configured, just send the alias as the model:

```bash
curl https://api.crossmodel.ai/v1/chat/completions \
  -H "Authorization: Bearer $CROSSMODEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cross-model-basic",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'
```