> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Define model aliases

> Give clients a plain model name that maps to one or more providers, and retarget it without changing any client.

An alias is a model name without a provider prefix, such as `claude-sonnet-5-5`, that the model router maps to one or more providers. Each target names a provider group and the model ID to send to it, so one alias can cover the same model under a different ID at each provider. Later targets are fallbacks. Because clients only know the alias, you can point it at another provider or model by changing the configuration, without changing any client. This topic shows you how to add aliases to a model router and how to retarget one.

## Prerequisites

Before you begin, make sure you have the following:

* A model router on the route, with the provider groups that the alias targets. For the steps, see [Route requests by model name](/configure/routing/model-router).
* Each target model on the allowed models list of at least one connection in its provider group.
* Permission to edit plugin instances.

## Add an alias

Aliases live in the `aliases` field of the model router's configuration. Each alias maps a name to an ordered list of targets:

| Field      | Description                                                                                |
| ---------- | ------------------------------------------------------------------------------------------ |
| `provider` | The name of a provider group in the same configuration.                                    |
| `model`    | The model ID to send to that group's connections. A connection in the group must allow it. |

When a client sends the alias, the gateway tries the first target's connections in that group's order. If they all fail with a status that triggers failover, it moves to the next target, and so on. Each attempt sends its own target's model ID.

To add an alias, do the following:

1. Select **Plugins**, select the **Configured** tab, and then open the model router instance for your route.

2. In **Configuration**, select **Edit as JSON**, and then add an `aliases` field next to `providers`. The following alias maps one name to a target on each of two providers. The gateway uses the first target whose provider serves the endpoint that the client called, and it fails over only between targets that serve that endpoint:

   ```json
   {
     "providers": {
       "openai": {
         "strategy": "fallback",
         "services": [{ "name": "openai-us" }]
       },
       "anthropic": {
         "strategy": "fallback",
         "services": [{ "name": "anthropic-prod" }]
       }
     },
     "aliases": {
       "claude-sonnet-5-5": [
         { "provider": "anthropic", "model": "claude-sonnet-5-5" },
         { "provider": "openai", "model": "gpt-5.5" }
       ]
     }
   }
   ```

   > **Note**
   >
   > This example needs OpenAI and Anthropic connections on one route. The console can't put connections with different API formats on one route, so create that route with the admin API. A `/v1/messages` request doesn't fall back to OpenAI, because OpenAI has no Anthropic Messages endpoint. For failover, use targets on providers that serve the same endpoint. For the steps, see [Create the model router](/configure/routing/model-router#create-the-model-router).

3. Select **Save**.

Fabric refuses an alias that breaks any of these rules:

* The name isn't empty, has no `/`, and isn't the name of a provider group.
* The alias has at least one target, and no target appears twice.
* Each target names a provider group, and a model that a connection in that group allows.

Names are matched exactly, including letter case. A client that sends `Claude-Sonnet-5-5` doesn't match the alias `claude-sonnet-5-5`.

## Map one model to each provider's ID

The same model often has a different ID at each provider. An alias hides that from clients. For example, with an `anthropic` group for the Anthropic API and a `bedrock` group for Amazon Bedrock, the following alias sends each provider the ID it expects:

```json
{
  "aliases": {
    "claude-sonnet": [
      { "provider": "anthropic", "model": "claude-sonnet-5-5" },
      { "provider": "bedrock", "model": "us.anthropic.claude-sonnet-5-5-v1:0" }
    ]
  }
}
```

Edit only the `aliases` field, and keep `providers` as it is.

## Retarget an alias

To move clients to another provider or model, edit the alias's targets and save. Clients keep sending the same name, and the change applies once the data plane receives the new configuration. For example, to make OpenAI the first choice for `claude-sonnet-5-5`, reorder its targets:

```json
{
  "aliases": {
    "claude-sonnet-5-5": [
      { "provider": "openai", "model": "gpt-5.5" },
      { "provider": "anthropic", "model": "claude-sonnet-5-5" }
    ]
  }
}
```

Edit only the `aliases` field, and keep `providers` as it is.

## Know how aliases behave

* **No translation.** A target works only on endpoints its provider serves. If a client sends an alias to `/v1/messages`, targets whose provider has no Anthropic Messages endpoint are skipped. If no target is left, the client gets `400`.
* **Embeddings use one model.** On `/v1/embeddings`, only the first target that serves the endpoint is used, because vectors from different models don't mix.
* **Grants narrow the targets.** If a caller has no grant for a **Gated** connection, the gateway skips it, so a caller without access to the first target starts at the next one. This doesn't apply on `/v1/embeddings`, or to a Responses request that carries `previous_response_id`. There, the gateway picks the target before it checks grants, so a caller without access to the first target gets `403`.
* **The model list shows aliases.** `GET /v1/models` lists each alias that the caller can use, with `owned_by` set to `fabric`.
* **The answer names the target.** The `x-fabric-model` response header names the `<provider>/<model>` of the target that answered, for example `openai/gpt-5.5`.

## Next steps

* [Choose a model](/use/llm/choose-a-model)
* [Route requests by model name](/configure/routing/model-router)