Model Aliases

Model aliases give callers stable names while AISIX controls how their requests reach upstream models.

Each AISIX model resource defines a caller-facing alias in display_name and the dispatch path behind it. A direct model maps the alias to one upstream model through one provider key. Routing, semantic, and ensemble models are virtual model aliases that resolve to one or more direct models at request time.

Start with direct models for the upstreams AISIX can call. Add a virtual model only when the caller-facing alias needs target selection or response synthesis.

Choose a Model Shape

AISIX supports the following dispatch shapes. Select a shape to open its configuration instructions. An embedding model dispatches like a direct model and adds vector metadata; it is not a virtual dispatch shape.

Model shape	How AISIX handles a request	Use when
Direct	Calls one upstream model through one provider key.	The alias has one upstream destination.
Embedding	Calls an embedding-capable upstream and records vector metadata for semantic comparisons.	A semantic router needs an embedding model.
Routing	Selects one direct target by failover, round robin, weights, cost, latency, or load.	One stable alias should distribute traffic or survive target failure.
Semantic	Embeds the latest user message and selects one direct target by meaning.	Different topics should reach different models without caller-side routing.
Ensemble	Calls several direct panel models and asks a direct judge model to synthesize one response.	One answer should incorporate multiple model responses.

A model resource contains exactly one dispatch shape: direct upstream fields, a routing block, a semantic block, or an ensemble block. AISIX Cloud references provider keys and other models by resource ID. The open-source AISIX gateway references them by display_name in resources.yaml. Both management paths reject resources that mix these shapes.

A direct model stores its upstream model in model_name. It can serve /v1/embeddings without embedding metadata. Add an embedding block only when the model will support semantic routing; Semantic Routing owns that configuration workflow. For supported providers and caller request formats, see Embeddings.

Prerequisites

Before starting, prepare the following:

• A provider key for each upstream credential the models will use.
• For AISIX Cloud, access to an environment, an attached gateway, and a write-scoped admin token. The provider key must allow the target environment, and you need its resource ID. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
• For the open-source AISIX gateway, a gateway that loads a declarative resources file containing the provider key. Models reference that key by its display_name.

Create a Direct Model

A direct model maps one caller-facing alias to one upstream model.

AISIX Cloud

Export the AISIX Cloud connection details and provider key ID:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash.
# The local On-Premises quickstart uses http://localhost:8080/api.
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

Create a direct model with the provider key ID you prepared:

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gpt-4o-prod",
    "model_name": "gpt-4o",
    "provider_key_id": "'"$PROVIDER_KEY_ID"'"
  }'

Every successful model creation request returns the created resource in the same response envelope. The following example shows the response for the direct model:

{
  "model": {
    "id": "677c847f-d92d-4f0e-b445-8b449764f06a",
    "env_id": "YOUR_ENVIRONMENT_ID",
    "kind": "direct",
    "display_name": "gpt-4o-prod",
    "model_name": "gpt-4o",
    "provider_key_id": "YOUR_PROVIDER_KEY_ID",
    "created_at": "2026-06-24T12:18:39Z",
    "updated_at": "2026-06-24T12:18:39Z"
  }
}

Copy the highlighted id. Routing, semantic, and ensemble models reference other models by this ID, and you also need it to update, inspect, or delete the model later. The examples for the other model shapes omit this common response.

The display_name is the name callers send in model. The model_name is the upstream model ID or deployment name AISIX sends to the provider. These values can be the same, but they do not have to be. The upstream provider comes from the referenced provider key.

On the Dashboard, the Upstream model id field suggests models published in the catalog for the selected provider key. Open the suggestions with the arrow in the field, or type to filter them. The field still accepts any value. Enter the ID verbatim for a preview model, a private deployment, or another model the catalog does not list. A Bring Your Own Endpoint provider key has no catalog entry, so the field stays a plain text input for it.

Open-Source AISIX Gateway

Add the model to the models collection and reference the provider key by name:

resources.yaml

models:
  - display_name: gpt-4o-prod
    provider: openai
    model_name: gpt-4o
    provider_key: openai-prod

The display_name remains the alias callers send in model, while model_name is the upstream model ID. The model entry declares provider explicitly and references the provider key by name. Validate and reload the complete resources file to apply the model.

Match Model Names with a Wildcard

A model alias whose display_name contains one * matches every requested model name that fits the pattern. One alias can therefore front many upstream models without a separate resource for each name.

A wildcard alias is a direct model. Set model_name to * to forward the matched portion upstream, or use a fixed value to send every match to one upstream model.

For AISIX Cloud, create the wildcard model with the provider key prepared earlier:

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "openai/*",
    "provider_key_id": "'"$PROVIDER_KEY_ID"'",
    "model_name": "*"
  }'

With this alias, a request for openai/gpt-4o uses upstream model gpt-4o, while a request for openai/o3-mini uses o3-mini. An exact alias always wins over a wildcard, and the most specific wildcard wins when several match.

Add the returned model ID to the caller API key's allowed_models list. Wildcard aliases do not appear in GET /v1/models, because they are patterns rather than concrete model names.

For the open-source gateway, declare the wildcard as a direct model and allow its name on the caller key:

resources.yaml

models:
  - display_name: openai/*
    provider: openai
    provider_key: openai-prod
    model_name: "*"

api_keys:
  - display_name: wildcard-caller
    key_env: CALLER_API_KEY
    allowed_models:
      - openai/*

Configure Optional Model Behavior

Most direct models only need a caller-facing alias, upstream model name, and provider key reference. Add optional fields only when the behavior is part of your traffic plan.

Common optional fields include:

• timeout, when a provider request should have a stricter per-request timeout.
• stream_timeout, when a streaming request should have a separate per-chunk read timeout.
• retries, when this model should be re-attempted a specific number of times after a retryable upstream failure. See Retry Budget.
• allowed_cidrs, when only callers from specific client IP ranges should use the model alias.
• background_model_check, when AISIX should probe a direct model outside the request path and mark it unhealthy after failed probes.
• cooldown, when real request failures should temporarily exclude a direct model from routing.
• rate_limit, when the limit should apply to one model alias. For details, see API Key and Model Rate Limits.

Routing models use the selected target's provider settings, timeout, health, and cooldown behavior. Semantic routers use the settings on the selected target and their embedding model, and honor a target's own gates at selection: a route target the caller's IP cannot reach falls through to the default target with the x-aisix-route header cleared, a router whose route target and default are both excluded returns the same 403 as a directly addressed model, and a target in cooldown or marked unhealthy by its background check is displaced by an available default. The embedding sub-call resolves its deadline from the router's embedding_timeout_ms, then the embedding model's own timeout, then the deployment default. A semantic router also carries its own retries as the group slot of the retry chain — see Retry Budget. Ensemble models use the settings on their panel and judge models. Configure provider settings, health, and cooldown behavior on the referenced direct models, not on the virtual model alias.

allowed_cidrs applies wherever the model is used, including when it serves as a target of a routing model. A caller outside the ranges cannot reach the model directly or through the routing model. AISIX resolves the client IP from the immediate peer unless proxy.real_ip is configured to trust forwarded headers from your load balancer or ingress.

Retry Budget

retries is the number of extra attempts AISIX makes against a model after a retryable upstream failure, such as a 5xx response or a transport error. AISIX uses this budget for Chat Completions, Text Completions, Messages, Count Tokens, and Responses. It also applies to Embeddings, Rerank, Audio, Image Generation, video submission and status polling, Provider Passthrough, and the direct model calls made by an ensemble. The setting applies to a model used on its own as well as one used as a routing target.

The retry budget does not apply to Realtime or the Files, Batches, and Fine-tuning APIs. Those routes can still surface upstream failures and contribute to cooldown state, but they do not repeat the request from this model setting.

AISIX resolves the budget for each attempt in this order:

Source	Applies When
retries on the model	The model sets it. This wins even when the model is a target of a routing model that sets its own retries.
routing.retries on the routing model	The target does not set retries. Acts as the group-wide default for every target.
retries on the semantic router	The dispatched route target does not set retries and the request came through a semantic router. The router's top-level value fills the same group slot as routing.retries does on a model group.
upstream.retries in the gateway configuration file	None of the above is set. Defaults to 2. See the Startup Configuration Reference.

Set retries: 0 to turn retrying off for a model. A 0 is an explicit setting at every level, never shorthand for leaving the field unset.

Two rules apply to the deployment-wide default only. A budget you configure explicitly, at either the model or the routing level, is always applied as written.

• Another target available. When a routing model has a further target to try and no retries is configured, AISIX moves to that target instead of repeating the current one. Repeating a failing target delays the failover without improving the outcome. The last target in the list has nothing to move to, so the default applies there.
• Request timeouts. A budget you did not configure is not spent on a timeout. A timeout is a deliberate limit on how long to wait for a model, and repeating the attempt multiplies that wait, usually with the same result. Configure retries on the model when a timeout should be retried. Timeouts still trigger failover to another target in both cases.

Each retry re-sends the full request body, and AISIX retries in addition to any retry the provider's own edge performs. Account for the combined number of upstream attempts before raising the budget on a high-volume model.

On the raw passthrough endpoint and the video submit call, a non-idempotent request is never retried once the provider has already returned its response status. A lost or invalid response body at that point means the operation committed upstream, so replaying it would duplicate the write. Failures during connection or send remain retryable everywhere.

Cost Metadata

Cost affects usage reporting, budget checks, and least_cost routing; it does not affect provider routing or access control.

In an AISIX Cloud deployment, the control plane resolves per-request cost from its pricing catalog and organization-level overrides. To set a price for a model the catalog does not cover, see Model Pricing.

For the open-source AISIX gateway, record pricing metadata with the cost field on the model in resources.yaml. The field records input and output cost in USD per 1,000 tokens:

models:
  - display_name: gpt-4o-prod
    provider: openai
    model_name: gpt-4o
    provider_key: openai-prod
    cost:
      input_per_1k: 0.0025
      output_per_1k: 0.01

For running a gateway from a resources.yaml file, see the Open-Source AISIX Gateway Quickstart.

Next Steps

You have now configured the caller-facing model alias. Continue with Caller API Keys to allow applications to use the alias and verify it through the proxy.