Service eligibility and regional restrictions
PuppyIP serves only compliant overseas businesses and their authorized personnel. Proxy services are not available in mainland China. The service may only be used for lawful business activities outside mainland China. Use of this service within mainland China is prohibited.
Hosting a proxy IP or server overseas does not change these restrictions. The service must not be provided to end users in mainland China through relaying, forwarding, sharing or resale. Before use, read the Terms of Service.
Key Takeaways
- A model alias gives a pool of models one name within its gateway; the same name on another gateway has a separate configuration.
- Enter the name without custom/ in the dashboard, which adds the prefix; call custom/support-fast and set cf-aig-gateway-id.
- Preferred routing tries eligible targets in order; smart routing chooses per request and falls back to the default order if it cannot rank them.
- AI Gateway's free core features do not make model inference free; check target eligibility, authentication, billing, and input protocol first.
One name points to a pool of candidate models
On November 4, 2026, Cloudflare announced model aliases for AI Gateway. Put several models behind one alias so your application can keep requesting the same name. When you need to change the models or routing, update the gateway configuration instead of changing the model name in your application.
An alias belongs to one gateway. Two gateways can have aliases with the same name, but their pools and routing settings are separate, so an inference request must target the gateway where the alias was created. An alias provides candidate selection and fallback; it does not guarantee that a model, provider, or request will succeed.
Prepare authentication and billing
Create an AI Gateway and turn on authentication. Then configure provider keys for the models in the alias, or set up Unified Billing. For inference through the REST API, the Cloudflare API token needs Account > Workers AI > Read permission. Managing aliases through the API uses AI Gateway permissions; these permissions serve different purposes.
AI Gateway is available on all plans, and the pricing page lists its core features (analytics, caching, and rate limiting) as free. That does not make model inference free. Unified Billing adds a 5% fee to purchased credits: a $100 credit purchase costs $105. Provider inference rates pass through without markup. Logs, Guardrails, or Logpush may be billed separately, so check current account pricing.
The pricing page does not list a separate model-alias charge or a region-by-region availability list. Check the applicable account terms for those details. Enterprise customers should confirm contract pricing with their account team.
Create an alias in the dashboard
In the Cloudflare dashboard, open AI > AI Gateway, select the gateway, go to Routing, and choose Create alias. In Alias name, enter a name without the custom/ prefix, such as support-fast. The dashboard adds custom/ in the list and in the name used for calls.
Choose a model under Models. To add fallbacks, add more models and drag them into order. Select a Routing algorithm, then create the alias. The default preferred order tries targets from top to bottom. Smart routing chooses a model for each request; if it cannot rank the candidates, the gateway uses the default order. A request's options.routing can override the saved algorithm.
Check that each target supports the protocol and input format used by your request; an alias does not make different model formats interchangeable. After a model or routing change, configuration may take time to propagate, and some requests may use cached settings while they refresh. Renaming an alias changes the name your application must request.
Call the alias through the REST API
Send the inference request to the Cloudflare REST API endpoint /client/v4/accounts/{account_id}/ai/run. Set model in the request body to custom/support-fast and provide input in a format accepted by that model. Also send the cf-aig-gateway-id header with the ID of the gateway where you created the alias. Without the correct gateway ID, the request cannot look up that gateway's alias as intended. Use the standard Authorization header with the Cloudflare API token as a Bearer token, and set Content-Type to application/json.
The gateway selects only models and providers that support the request protocol and pass gateway checks. If an attempt fails, it may try another eligible target. Routing does not bypass authentication, billing, or gateway policies. Check candidate models with a real request format you plan to use; configuring fallbacks is not a promise of successful service.
Manage the full configuration through the API
The alias management endpoint is /client/v4/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/model_aliases. Use GET to list or read an alias, POST to create one, PUT to replace one, and DELETE to remove one. In POST and PUT requests, name omits custom/. The configuration includes a model list and can include providers for each model. To read, replace, or delete one alias, append /{alias_id}; listing and creation use the collection path.
A providers list restricts which providers can serve that model and sets their priority in the listed order. If you omit providers, the gateway can use providers registered for that model. Provider restrictions are configured through the API; the dashboard editor selects models only. PUT replaces the entire configuration, so include every model and provider restriction you want to keep. Omitting routing, or setting it to null or an empty object, clears the saved routing preferences.
Check name rules, limits, and errors
Each gateway supports up to 100 aliases, and each alias contains 1 to 50 model entries. Names must be unique within the gateway and 1 to 64 characters long. Use lowercase letters and numbers, with single periods, underscores, or hyphens as separators. For example, support-fast is valid; Support Fast, support--fast, and support- are not.
A 404 with Model not found means the selected gateway has no alias with that name. Check the gateway ID, alias spelling, and custom/ prefix.
A 400 with has no available models means none of the targets resolve to available, protocol-compatible models. Check the model IDs and provider restrictions.
A 503 with Model aliases are temporarily unavailable means the gateway cannot read the configuration. The documentation suggests retrying, but does not guarantee a successful retry or recovery time.
Sources
Frequently Asked Questions
How do I route by conditions, percentages, or limits within a flow?
Use dynamic routes for those controls. Model aliases are for choosing a model pool by one name, with an ordered preference or smart selection; use dynamic routes for conditional branches, percentage splits, and limits within a routing flow.
Can an alias target another alias, or use x402 payments?
No. Model aliases cannot reference another custom/ alias and do not support x402 payments. Add eligible catalog models directly to the pool and handle billing through the applicable provider and account setup.