Smart API Keys: one key for every model your account can use
A Smart API Key is bound to auto instead of a fixed routing group. It resolves a group on each request and orders candidates by a routing strategy that you choose.
An ordinary Modelflare API key is bound to one routing group, so it can only call the models that group serves. A Smart API Key removes that restriction. It can call every model the account has access to, and the gateway picks the routing group for each request. Client code stays the same: same base URL, same Authorization: Bearer header.
This article covers how a Smart API Key resolves a request, which routing strategies are available, how billing works, and when to use an ordinary key instead.
Creating one
In API Keys, select Create Smart API Key. Requests authenticate the same way as with any other key:
Authorization: Bearer YOUR_MODELFLARE_API_KEY
Send this header on every request, including video polling and media downloads. Do not put the key in a browser, mobile app, or public repository.
How a request is resolved
The routing group is resolved per request and is not stored on the key. On each call the gateway goes through four steps:
- Collect groups. Every routing group the account may use.
- Keep what serves the model. Only groups that currently have a channel for the model ID in the request body.
- Order by strategy. Balanced, stability first, or low price first.
- Send to the first candidate. If that group runs out of usable channels, the request continues to the next one.
Step 2 runs on every request. A model served by only one group still works, and a group that is temporarily unusable is skipped instead of failing the call.
Routing strategies
| Strategy | Order of candidate groups |
|---|---|
| Balanced (default) | Starts in the middle of the price range, works up to the most expensive candidate, then back down through the cheaper ones. |
| Stability first | Highest group multiplier first. |
| Low price first | Lowest group multiplier first. |
The strategy is a property of the key. It can be changed on an existing key, and the next request uses the new order.
Billing and logs
A request is billed at the multiplier of the group that actually served it, not the strategy's first choice. The consume log records the resolved group and the strategy, so you can see after the fact when a request moved. Usage and cost for every request are visible in the console; see Usage and cost.
Rules
- No per-model allowlist. A Smart API Key always follows the account's current model access, so a newly released model works without editing the key.
- Standard key controls apply. Quota, expiry date, and IP allowlist work as on any other key.
- No manual fallback list. A Smart API Key already walks every group the account can use. Ordered fallback chains are a feature of ordinary keys; see Group failover.
Image, video, and coding agents
Image and video endpoints accept either a Smart API Key or a key on the media group. The Seedance asset-management routes accept the same two key types. Accounts created through Castaly already have a key named Castaly that routes across every group enabled for the account.
Each documentation page, including the coding-agent guides, links to Smart API Key creation. Because the key follows the account's model access, the same key can be used across clients without selecting a group for each model.
When to use an ordinary key
An ordinary key is the better choice when you need a fixed route. It names one primary group and, optionally, an ordered list of fallback groups that you control. Use it when a workload must stay on a specific group, or when you want to set the fallback order by hand rather than through a strategy. The model groups and failover article covers that model in detail.
Checking what a key can call
Both key types can list the models they are able to call:
curl https://modelflare.dev/v1/models \
-H "Authorization: Bearer YOUR_MODELFLARE_API_KEY"
The response is not a price list. Prices, groups, and protocol labels are on Models & Pricing. For business and enterprise inquiries, contact business@modelflare.dev.