Routing and models

A request crosses several deliberate boundaries before it reaches an upstream account: client key, requested model or alias, account eligibility, priority policy, and fallback. This page makes that route inspectable.

Choose the client surface

Clients stay on one gateway base URL. Change the model field to select an upstream provider; do not invent a separate URL for every provider.

Selection order

1. 1
   Accept the client key.

   The request must pass the shared gateway key or the managed API-key rules before any provider is contacted.

2. 2
   Resolve the requested model.

   A natural model name selects its provider, a three-letter prefix forces one, and ctm: resolves a custom alias.

3. 3
   Apply the boundary.

   Managed-key provider/account rules and input controls are applied to each concrete route target. Aliases are routing policies, not independent key-scope entries.

4. 4
   Build an eligible account pool.

   Disabled, failed, cooling-down, and quota-exhausted accounts are excluded before selection.

5. 5
   Use priority where present.

   Eligible priority accounts are selected before the normal pool for that provider.

6. 6
   Fail over and leave evidence.

   A custom alias may try another target; usage history records the resulting route so the decision can be checked.

Force a provider when the name is ambiguous

For example, gem:gemini-2.5-pro forces Gemini even when another provider could recognize a similar model name. Use a ctm: alias when clients should see a stable name while you manage targets and fallbacks behind it.

Choose the right control

Use priority routing for temporary account draining. Use custom models for stable client-facing aliases and cross-provider failover. Use API keys for tenant or client access boundaries.