Define model aliases
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.
- 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:
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:
-
Select Plugins, select the Configured tab, and then open the model router instance for your route.
-
In Configuration, select Edit as JSON, and then add an
aliasesfield next toproviders. 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: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/messagesrequest 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. -
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:
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:
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 gets400. - 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 carriesprevious_response_id. There, the gateway picks the target before it checks grants, so a caller without access to the first target gets403. - The model list shows aliases.
GET /v1/modelslists each alias that the caller can use, withowned_byset tofabric. - The answer names the target. The
x-fabric-modelresponse header names the<provider>/<model>of the target that answered, for exampleopenai/gpt-5.5.

