smart-api-key.html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Smart API Keys: one key for every model your account can use | Modelflare Blog</title>
<meta name="description" content="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."><meta property="og:image" content="images/smart-api-key-cover.jpg">
<style>
:root{--bg:#0b1020;--card:#121a2f;--text:#e8ecf7;--muted:#9aa6c2;--accent:#8b5cf6;--accent2:#ec4899;--border:rgba(255,255,255,.08)}
*{box-sizing:border-box}
body{margin:0;font-family:ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,Helvetica,Arial,sans-serif;background:radial-gradient(1200px 600px at 10% -10%,#2a1850 0%,transparent 50%),radial-gradient(900px 500px at 100% 0%,#3b0f2e 0%,transparent 45%),var(--bg);color:var(--text);min-height:100vh;line-height:1.65}
.wrap{max-width:860px;margin:0 auto;padding:28px 18px 64px}
header.top{display:flex;flex-wrap:wrap;gap:14px;align-items:center;justify-content:space-between;margin-bottom:28px;font-size:14px}
header.top a{color:var(--muted);text-decoration:none}header.top a:hover{color:#fff}
header.top .brand{color:#fff;font-weight:700;font-size:16px}
header.top nav{display:flex;flex-wrap:wrap;gap:14px}
h1{font-size:clamp(26px,4.6vw,38px);line-height:1.2;margin:0 0 12px}
h2{font-size:22px;margin:36px 0 10px}h3{font-size:17px;margin:24px 0 8px;color:#d6c7ff}
p,li{color:#cfd6e8}a{color:#c4b5fd}
.lead{color:var(--muted);font-size:17px}
article img{max-width:100%;height:auto;border-radius:12px;border:1px solid var(--border);display:block;margin:18px auto 6px}
article p em:only-child{display:block;text-align:center;color:var(--muted);font-size:14px}
pre{background:#070b16;border:1px solid var(--border);border-radius:12px;padding:0;overflow-x:auto}
pre code.hljs{background:transparent;padding:14px 16px;font-size:13.5px;line-height:1.55}
code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:.92em}
p code,li code,td code{background:rgba(139,92,246,.14);padding:1px 5px;border-radius:5px}
table{border-collapse:collapse;width:100%;font-size:14px;margin:14px 0;display:block;overflow-x:auto}
th,td{border:1px solid var(--border);padding:8px 10px;text-align:left;vertical-align:top}th{background:var(--card)}
hr{border:0;border-top:1px solid var(--border);margin:32px 0}
.list{display:grid;gap:14px}
.card{display:flex;gap:16px;background:var(--card);border:1px solid var(--border);border-radius:16px;padding:18px;text-decoration:none;color:inherit}
.card:hover{border-color:rgba(139,92,246,.5)}
.card img{width:200px;height:105px;object-fit:cover;border-radius:10px;flex-shrink:0}
.card h2{font-size:18px;margin:0 0 6px;color:#fff}.card p{margin:0;color:var(--muted);font-size:14px}
footer{margin-top:48px;padding-top:18px;border-top:1px solid var(--border);color:var(--muted);font-size:13px}
footer a{color:var(--muted)}
@media(max-width:600px){.card{flex-direction:column}.card img{width:100%;height:auto;aspect-ratio:1200/630}}
</style>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@highlightjs/cdn-assets@11.9.0/styles/github-dark.min.css"><script src="https://cdn.jsdelivr.net/npm/@highlightjs/cdn-assets@11.9.0/highlight.min.js"></script><script>document.addEventListener("DOMContentLoaded",()=>hljs.highlightAll());</script>
</head>
<body><div class="wrap"><header class="top"><a class="brand" href="index.html">Modelflare Blog</a><nav><a href="https://modelflare.dev/?utm_source=huggingface&utm_medium=space&utm_campaign=blog">modelflare.dev</a><a href="https://docs.modelflare.dev/?utm_source=huggingface&utm_medium=space&utm_campaign=blog">Docs</a><a href="https://castaly.modelflare.dev/?utm_source=huggingface&utm_medium=space&utm_campaign=blog">Castaly</a><a href="https://huggingface.co/Modelflare" target="_top">Hugging Face org</a></nav></header>
<article><h1>Smart API Keys: one key for every model your account can use</h1>
<p class="lead">A Smart API Key is bound to <code>auto</code> instead of a fixed routing group. It resolves a group on each request and orders candidates by a routing strategy that you choose.</p>
<img src="images/smart-api-key-cover.jpg" alt="Illustration: a key module feeding a single route">
<hr />
<p>An ordinary <a href="https://modelflare.dev/?utm_source=huggingface&amp;utm_medium=space&amp;utm_campaign=smart-api-key">Modelflare</a> 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 <code>Authorization: Bearer</code> header.</p>
<p>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.</p>
<h2>Creating one</h2>
<p>In <a href="https://modelflare.dev/keys?utm_source=huggingface&amp;utm_medium=space&amp;utm_campaign=smart-api-key">API Keys</a>, select <strong>Create Smart API Key</strong>. Requests authenticate the same way as with any other key:</p>
<pre><code class="language-http">Authorization: Bearer YOUR_MODELFLARE_API_KEY
</code></pre>
<p>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.</p>
<h2>How a request is resolved</h2>
<p>The routing group is resolved per request and is not stored on the key. On each call the gateway goes through four steps:</p>
<ol>
<li><strong>Collect groups.</strong> Every routing group the account may use.</li>
<li><strong>Keep what serves the model.</strong> Only groups that currently have a channel for the model ID in the request body.</li>
<li><strong>Order by strategy.</strong> Balanced, stability first, or low price first.</li>
<li><strong>Send to the first candidate.</strong> If that group runs out of usable channels, the request continues to the next one.</li>
</ol>
<p>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.</p>
<h2>Routing strategies</h2>
<table>
<thead>
<tr>
<th>Strategy</th>
<th>Order of candidate groups</th>
</tr>
</thead>
<tbody>
<tr>
<td>Balanced (default)</td>
<td>Starts in the middle of the price range, works up to the most expensive candidate, then back down through the cheaper ones.</td>
</tr>
<tr>
<td>Stability first</td>
<td>Highest group multiplier first.</td>
</tr>
<tr>
<td>Low price first</td>
<td>Lowest group multiplier first.</td>
</tr>
</tbody>
</table>
<p>The strategy is a property of the key. It can be changed on an existing key, and the next request uses the new order.</p>
<h2>Billing and logs</h2>
<p>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 <a href="https://docs.modelflare.dev/guides/usage-and-cost/?utm_source=huggingface&amp;utm_medium=space&amp;utm_campaign=smart-api-key">Usage and cost</a>.</p>
<h2>Rules</h2>
<ul>
<li><strong>No per-model allowlist.</strong> A Smart API Key always follows the account's current model access, so a newly released model works without editing the key.</li>
<li><strong>Standard key controls apply.</strong> Quota, expiry date, and IP allowlist work as on any other key.</li>
<li><strong>No manual fallback list.</strong> A Smart API Key already walks every group the account can use. Ordered fallback chains are a feature of ordinary keys; see <a href="https://docs.modelflare.dev/guides/features/group-failover/?utm_source=huggingface&amp;utm_medium=space&amp;utm_campaign=smart-api-key">Group failover</a>.</li>
</ul>
<h2>Image, video, and coding agents</h2>
<p>Image and video endpoints accept either a Smart API Key or a key on the <code>media</code> group. The Seedance asset-management routes accept the same two key types. Accounts created through Castaly already have a key named <code>Castaly</code> that routes across every group enabled for the account.</p>
<p>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.</p>
<h2>When to use an ordinary key</h2>
<p>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 <a href="model-groups-and-failover.html">model groups and failover</a> article covers that model in detail.</p>
<h2>Checking what a key can call</h2>
<p>Both key types can list the models they are able to call:</p>
<pre><code class="language-bash">curl https://modelflare.dev/v1/models \
  -H &quot;Authorization: Bearer YOUR_MODELFLARE_API_KEY&quot;
</code></pre>
<p>The response is not a price list. Prices, groups, and protocol labels are on <a href="https://modelflare.dev/pricing?utm_source=huggingface&amp;utm_medium=space&amp;utm_campaign=smart-api-key">Models &amp; Pricing</a>. For business and enterprise inquiries, contact <a href="mailto:business@modelflare.dev">business@modelflare.dev</a>.</p></article><p><a href="index.html">&larr; All articles</a></p>
<footer>Modelflare on Hugging Face: <a href="https://huggingface.co/spaces/Modelflare/start" target="_top">start</a> · <a href="https://huggingface.co/spaces/Modelflare/openai-sdk" target="_top">openai-sdk</a> · <a href="https://huggingface.co/spaces/Modelflare/coding-agents" target="_top">coding-agents</a> · <a href="https://huggingface.co/spaces/Modelflare/api-recipes" target="_top">api-recipes</a> · <a href="https://huggingface.co/datasets/Modelflare/api-examples" target="_top">api-examples dataset</a><br>Business: <a href="mailto:business@modelflare.dev">business@modelflare.dev</a></footer></div></body>
</html>