Resource Model

AISIX gateways use a small set of resources to turn a caller request into an authenticated upstream provider request.

The main resources are caller API keys, models, and provider keys. Virtual model shapes and policy resources build on that path when you need target selection, response synthesis, rate limits, guardrails, caching, observability, or AISIX Cloud budget checks.

Core Traffic Resources

Most AISIX traffic starts with three resources: a caller API key, a model, and a provider key. Together, they decide who can call the gateway, which model name the caller can use, and which upstream provider AISIX calls. For a single-target model, the same relationship applies to AISIX Cloud and the open-source AISIX gateway:

The products manage and reference these resources differently:

Product	Management relationship
AISIX Cloud	Caller API keys and models belong to an environment and reference related resources by ID. Provider keys belong to the organization and must be allowed in the environment. The control plane projects the resulting configuration to attached gateways.
Open-source AISIX gateway	The resources are declared in resources.yaml. Caller API keys reference model display_name values, and models reference provider key display_name values.

In AISIX Cloud, create or update each resource through the dashboard or Admin API, then use Resource Projection to verify that the change reached the gateways. In the open-source gateway, validate the complete resources file and reload it as one configuration snapshot. A failed reload keeps the last valid snapshot active.

In the Open-Source AISIX Gateway Quickstart, the caller API key is YOUR_CALLER_API_KEY, the model alias is gpt-4o-mini, the provider key stores the OpenAI credential, and the upstream model is also gpt-4o-mini.

In production, the alias and upstream model do not need to match. For example, an application can keep sending prod-chat while the gateway changes the upstream model, provider key, or routing policy behind that alias.

Caller API Key

A caller API key is the gateway credential an application uses when it calls AISIX.

The key authenticates the caller and controls which model aliases that caller may use. For key hashing, rotation, and the model allowlist, see Caller API Keys.

Model

A model is the gateway-facing model name callers send in the request body.

For a direct model, the caller-facing alias can differ from the upstream provider's model ID. The model also points to the provider key AISIX should use for the upstream call. Virtual models resolve the alias through a routing, semantic, or ensemble decision before AISIX reaches a direct model.

For each model shape and its configuration, see Model Aliases.

Provider Key

A provider key stores the upstream credential and connection settings AISIX uses after it resolves a model.

Provider keys keep upstream secrets out of application code and let multiple models reuse the same upstream account, base URL, and adapter family. For credential fields, base URL behavior, provider labels, and adapters, see Provider Keys. For changing a shared upstream credential, see Provider Key Rotation.

In the open-source gateway, each provider key declares its adapter. AISIX Cloud derives the adapter for catalog providers and accepts an explicit adapter for bring-your-own providers.

Model Dispatch Shapes

Every model has a display_name, which is the alias used by callers. In AISIX Cloud, references between model resources use resource IDs. For the open-source AISIX gateway, references in resources.yaml use display_name values. The remaining fields define one dispatch shape:

Shape	Resource relationship
Direct	Stores an upstream model_name and references one provider key.
Routing	References several direct targets and selects one by its routing strategy.
Semantic	References an embedding-capable direct model, a default direct model, and direct targets for its semantic routes.
Ensemble	References direct panel models and a direct judge model.

The four shapes are mutually exclusive. A resource cannot combine direct upstream fields with a routing, semantic, or ensemble block.

An embedding model remains a direct model. Its embedding block records vector dimensions and normalization behavior so the model can serve embeddings and support semantic routing.

Callers can keep one stable alias while operators change the direct upstream, routing targets, semantic routes, or ensemble members behind it. The caller API key must allow the alias named in the request; AISIX selects or invokes referenced models internally.

For detailed behavior, see Routing and Failover, Semantic Routing, and Ensemble Models.

Policy Resources

Policy resources add gateway behavior around the caller API key, model, and provider key path.

Rate limits control request rate and concurrency. Guardrails check request or response content. Caching can reuse chat-completion responses. Observability exporters send gateway request telemetry to an OTLP/HTTP, object storage, Aliyun SLS, or Datadog destination.

Budget checks are enforced through AISIX Cloud control-plane policy. The open-source AISIX gateway does not expose a local budget resource.