Model aliases

A model alias is a pool of models that your application calls by a single name, such as custom/support-fast. For each request, AI Gateway picks a model from the pool in one of two ways:

• Default order: Try the models in the order you set, and fall back to the next model if one fails.
• Smart routing: Choose the model for each request.

Because your application only references the alias name, you can change the models or routing algorithm on your gateway without updating your code. Aliases belong to individual gateways, so a custom/support-fast alias on one gateway is separate from one with the same name on another.

For conditional branches, percentage splits, or limits within a routing flow, use dynamic routes instead.

• Create a gateway and turn on authentication.
• Configure Unified Billing or store provider keys for the models you want to use.
• To call the REST API, create a Cloudflare API token with Account > Workers AI > Read permission. This differs from the AI Gateway permissions used to manage aliases.

Not every catalog model is available as an alias target. Targets must be available to alias routing and support the protocol format you use.

The alias appears in the Routing list with its custom/ prefix. Select its name to edit the models or routing algorithm, then select Save alias. Renaming an alias changes the name your application must request.

Configuration changes can take time to reach requests served from different locations. A request may use a cached alias configuration while it refreshes.

Routing options supplied with a request override the alias's saved routing algorithm.

Only models and providers that support the request format and pass gateway checks are eligible. A failed attempt can fall back to another eligible model or provider. This does not bypass authentication, billing, or gateway policies.

Use the REST API with custom/<alias-name> as the model. Include the cf-aig-gateway-id header to select the gateway where you created the alias.

Set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN to your account ID and API token. Replace my-gateway with your gateway ID and custom/support-fast with your alias.

curl "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "cf-aig-gateway-id: my-gateway" \
  --data '{
    "model": "custom/support-fast",
    "input": {
      "messages": [
        { "role": "user", "content": "Reply with a short greeting." }
      ]
    }
  }'

The request uses the alias configuration on my-gateway. Use an input format supported by the models you select. An alias does not make model-specific input formats interchangeable.

To override the alias's routing preferences for one request, add options.routing alongside model and input:

{
	"model": "custom/support-fast",
	"input": {
		"messages": [{ "role": "user", "content": "Reply with a short greeting." }]
	},
	"options": {
		"routing": {
			"algorithm": "preferred"
		}
	}
}

Alias configuration uses /accounts/{account_id}/ai-gateway/gateways/{gateway_id}/model_aliases under the Cloudflare API's /client/v4 prefix. These operations require AI Gateway permissions, rather than the Workers AI permission used for inference.

For POST and PUT, provide an alias name without custom/, a list of catalog models, and optional routing preferences:

{
	"name": "support-fast",
	"models": [
		{ "model": "openai/gpt-4.1-nano", "providers": ["openai"] },
		{ "model": "anthropic/claude-sonnet-4.6", "providers": ["anthropic"] }
	],
	"routing": {
		"algorithm": "preferred"
	}
}

Each model's optional providers list restricts its providers and sets their preferred order. Omit providers to allow the gateway's registered providers for that model. Provider restrictions are configured through the API. The dashboard editor selects models only.

PUT replaces the whole configuration. Include every model and provider restriction you want to keep. Omitting routing, or setting it to null or {}, clears the alias's routing preferences.

• Each gateway supports up to 100 aliases.
• An alias must contain between 1 and 50 model entries.
• Names must be unique within the gateway and contain 1–64 characters. Use lowercase letters and numbers, optionally separated by a single ., _, or -. For example, support-fast is valid. Support Fast, support--fast, and support- are not.
• An alias cannot reference another custom/ alias.
• Models must support a shared protocol format for the request. Native-only model formats are not available through aliases.
• Aliases do not support x402 payments.