Skip to main content

Route a Model Alias

Tasks

Name a model once and let a route decide which provider serves it. For how aliases fit into routing, see Model aliases.

Before you start, add the providers and the route. See Add a route. A route that mixes Anthropic and OpenAI-family members needs Allow cross-provider members.

Add an alias in the console​

  1. Go to Settings → Providers, switch to the Routes tab, and open the route's Edit action, or select Add Route.
  2. On the Aliases step, select Add alias and enter the name clients send, such as fast-coder.
  3. Under Model sent to the member, enter the model each member receives, such as deepseek-chat for a DeepSeek member. Leave a member empty to skip it for the alias.
  4. Select Save. An alias name that contains a wildcard, repeats within the route, or has no model for any member is flagged on the step. When the alias equals another route's exact model pattern, the save is rejected and the error shows on the Aliases step.

Removing a member from the route removes its models from the route's aliases when you save.

Add an alias through the admin API​

Send the route with its modelAliases to PUT /api/v1/llm-routes/{name}. The body is the whole route, so include its model patterns and members. Each alias has a name and a wireModels map from member provider name to the model that member is sent:

curl -X PUT "https://YOUR_WORKSPACE_URL/api/v1/llm-routes/free-credits" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"free-credits","enabled":true,"models":["deepseek-*"],"allowTranslation":true,
       "members":[{"provider":"deepseek-credits"},{"provider":"groq-free"},{"provider":"claude-api"}],
       "modelAliases":[{"name":"fast-coder","wireModels":{
         "deepseek-credits":"deepseek-chat","groq-free":"moonshotai/kimi-k2-instruct","claude-api":"claude-haiku-4-5"}}]}'

The request returns 400 when an alias contains a wildcard, repeats within the route, maps a provider that isn't a member, or equals another route's exact model pattern.

Add an alias in the deployment configuration​

A deployment whose routes come from its configuration file sets aliases on the pool under llmProxy.pools, which becomes the route. Each alias has a name and a wireModels map from member provider name to the model that member is sent:

llmProxy:
  pools:
    - name: free-credits
      enabled: true
      allowTranslation: true
      match:
        models: ["deepseek-*"]
      members:
        - upstream: deepseek-credits
        - upstream: groq-free
        - upstream: claude-api
      modelAliases:
        - name: fast-coder
          wireModels:
            deepseek-credits: deepseek-chat
            groq-free: moonshotai/kimi-k2-instruct
            claude-api: claude-haiku-4-5

Restart AIControls. An invalid alias fails startup with a message naming the pool and the alias. GET /api/v1/model-aliases lists the aliases of the enabled pools, read-only: each entry has the alias name, its pool, its wireModels, and source (db or config). See Configuration file for the other pool keys.

Use the alias​

Clients send the alias as the model, for example with Claude Code:

claude --model fast-coder

Each member that answers gets its own wire model. A member with no wire model for the alias is left out. When Access Bindings grant models, the caller also needs a grant that covers the alias name.

Check where an alias routes​

Send the alias to POST /api/v1/routing/resolve:

curl -X POST "https://YOUR_WORKSPACE_URL/api/v1/routing/resolve" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"model":"fast-coder"}'

matched_on is model-alias when the alias selected its route, alias and pool name the alias and the route, and order lists the members the request tries. members lists the same members in the same order, each with the wire model it receives:

{
  "upstream": "deepseek-credits",
  "matched_on": "model-alias",
  "alias": "fast-coder",
  "pool": "free-credits",
  "strategy": "failover",
  "order": ["deepseek-credits", "groq-free", "claude-api"],
  "members": [
    {"upstream": "deepseek-credits", "vendor": "deepseek", "provider": "deepseek", "wireModel": "deepseek-chat", "format": "anthropic", "translated": false, "parked": false},
    {"upstream": "groq-free", "vendor": "groq", "provider": "groq", "wireModel": "moonshotai/kimi-k2-instruct", "format": "openai-chat", "translated": false, "parked": false},
    {"upstream": "claude-api", "provider": "anthropic", "wireModel": "claude-haiku-4-5", "format": "anthropic", "translated": false, "parked": false}
  ]
}

Add "format": "anthropic" or "format": "openai-chat" to the request to see which members translate that client's requests. See Routing API for every member field.

Last updated on