Model Remaps
What a remap is
Every remap lives on a FreeRouter key, next to its routing rule, and maps one incoming model id to one destination: a stored provider key plus a literal upstream model id. When a request arrives carrying that model, FreeRouter serves it from the destination instead of the rule's normal targets. Your application keeps sending the same model id it always has — the swap happens entirely inside FreeRouter.
Typical uses:
- Model migration — a gateway deprecates a model. Point the old id at its replacement; clients keep calling the old id until you update them (or forever).
- Cost arbitrage — serve a premium model id from a cheaper gateway's equivalent, pocketing the spread.
- Canary a replacement — send a slice of traffic to the new model (see percentages), compare quality, then cut over.
- Catch-all fallback — route every model without its own rule to one safe default (see matching).
How matching works
Matching is by exact incoming model id, trimmed and case-insensitive. Two extra rules decide which remaps apply:
- Use
*as the incoming model to catch everything without its own rule — an exact match always beats the catch-all. - Several enabled remaps for the same model (or several
*remaps) split that model's traffic — see splitting one model across destinations.
Remaps apply to every API shape (OpenAI, OpenRouter, Anthropic, Google), because matching keys off the request's normalized model, not its wire format.
Percentages and fall-through
Each remap carries a percent (1–100, default 100), rolled per request. At 100% every matching request is rewritten. Below 100%, that share is rewritten and the rest falls through to the key's normal targets — so percent: 20 is a 20% canary with the other 80% following the rule untouched.
Splitting one model across destinations
Give the same incoming model (or *) more than one enabled remap and each remap's percent becomes its slice of that model's traffic; one roll per request walks the slices in listed order, and the unclaimed share falls through to the rule.
split rule picks a first target per request in proportion to the weights — relative integers, normalized to 100% — then fails over through the remaining targets in listed order. A weight of 0 is failover-only: that target is never the first pick, but it is still tried if the chosen gateway fails. Bottom: a model remap runs first and rewrites a slice of one incoming model to a fixed target and upstream_model; whatever share it does not claim falls through to the rule.- The enabled slices for one model must add up to 100% or less — saving more answers
400. Switched-off remaps don't count. - Slices back each other up: if the picked destination fails retryably, the model's other remaps are tried next, in listed order, before the normal targets.
- The split is random per request, not a strict rotation — it evens out over traffic, not over the next few calls.
Example
Keep sending z-ai/glm-4.5-flash from your app: 20% is served from Darkbloom's model, 80% follows the normal rule, and every other model goes to the Vercel fallback:
{
"strategy": "priority",
"targets": [
{ "provider_key_id": "<openrouter-key-id>", "gateway": "openrouter" }
],
"model_remaps": [
{ "match": "z-ai/glm-4.5-flash", "percent": 20,
"provider_key_id": "<darkbloom-key-id>", "gateway": "darkbloom",
"upstream_model": "qwen3.6-35b-a3b-vl-mtp-mxfp8" },
{ "match": "*",
"provider_key_id": "<vercel-key-id>", "gateway": "vercel",
"upstream_model": "fallback-model" }
]
}
Reliability: remaps fail safe
A remap never makes a key less reliable than its rule alone:
- If the destination errors retryably — the same set as any routing target:
401,402,403,404,429,5xx, a timeout or a connection error — FreeRouter tries the model's other remaps, then fails over to the normal targets, exactly like ordinary failover. - A definitive answer from the destination (success or a non-retryable client error such as a
400) returns directly. - A remap hop waits the key's failover timeout, then that gateway's learned budget, then the 5s default, for its first byte on a streaming request. It never uses a per-target
ttfb_ms— even when the destination provider key also sits in the rule with one. - A remap whose destination can't be served — deleted or disabled provider key, kill-switched or non-routable gateway — is skipped: the model's other remaps, then normal routing, run instead.
402 — remaps alone never serve a key. Keep at least one live target on every key that carries remaps.
The upstream model is sent literally
The upstream_model id goes to the destination provider exactly as written — FreeRouter skips its usual model-id translation for remapped requests, because the remap is the mapping. In the dashboard's Model remaps editor, the upstream-model field offers the destination's live model list, fetched from that provider through your stored key, so ids are chosen, not typed.
Remaps on systemone keys
Remaps work on systemone (Decisions) keys too, with the same matching, percentages and fall-through. The typical use is swapping one decision model for another without touching client code — for example, the client keeps sending jev-latest and a remap sends it to perplexity/pplx-decider-v1.1-27b through an OpenRouter provider key. Two rules keep it honest:
- The destination must carry the model. On a
systemonekey, destinations are Decisions hosts, and each carries specific models (see which host carries which model). TypeSafe, Requesty, and Ramp Router serve Jev only, Cloudflare serves Clef, OpenAI serves GPT-6 Luna, Celeris serves its own decision model, and Vercel serves its own decision catalog; OpenRouter carries every vendor's decider — saving a remap whose destination cannot carry its model answers400. Jev aliases are translated per host, so a remap tojev-latestworks on every Jev host. - A remap is the only way the model changes. FreeRouter never swaps decision models on its own; probabilities are not comparable across models, so recheck any confidence thresholds when you remap. If the remap destination fails with a retryable error, the model's other remaps are tried, then the request falls through to the key's targets with the original model. An image request skips a remap whose model reads text only.
Chat keys cannot remap to TypeSafe or to a Jev id — Jev is a decision model, so call it with a systemone key.
Limits
- Max 20 remaps per key.
- Model ids (match and upstream) max 200 characters.
- The enabled remaps for one incoming model id (or
*) total at most 100% (ids compared case-insensitively). Switched-off remaps don't count, so you can stage a replacement next to the live one and swap the switches when you're ready. - Switched-off remaps still count toward the 20-per-key limit — delete, don't disable, what you won't use.
Setting remaps
Three writers, one stored shape:
- Dashboard — the per-key Model remaps editor on the API Keys tab, with the live upstream-model picker per destination row. Each row has an on/off switch: a switched-off remap stays saved but never matches, so you can stage a remap, test the base rule, and enable it later.
- Management API —
model_remapsonPUT /api/v1/keys/:id/routing(orroutingonPOST /api/v1/keys). Destinations attach stored provider keys by UUID and go through the same workspace checks as targets. See PUT routing. - MCP — the
set_routingtool. See MCP Server.
Deleting a provider key strips it from remaps as well as targets; disabling keeps the references, so re-enabling restores them. After saving, the dashboard confirms the proxy cache reloaded the new rule.
Seeing remaps in flight
- The dashboard Logs tab marks remap-served attempts with a
remapbadge (expand a row for the attempt path). X-FreeRouter-Attemptscounts the remap try like any other attempt.- Request logs keep the client-requested model — the rewrite is visible in the attempt stages, not the top-line model.
Limitations
- Playground and Test-key don't evaluate remaps. Both exercise the key's base targets with a fixed test model, so a green test means base connectivity, not remap correctness. Verify remaps with live traffic and check the Logs tab for the
remapbadge. GET /v1/modelsignores remaps — there's no model in the request to match on.