Model Remaps

A remap rewrites one incoming model to a fixed provider/model before a key's routing rule runs — migrate models, arbitrage cost, or canary a replacement with zero client changes.

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.

Percentage split and remap fan-out: one FreeRouter key splits 60, 30 and 0 across gateways A, B and C, where weight 0 is failover-only; a model remap sends a 20 percent slice of model X to gateway C with an upstream model, and the remaining 80 percent falls through to the base rule. %-split — one key, three targets FreeRouter key strategy: split 60% 30% 0 Gateway A first pick 6 in 10 Gateway B first pick 3 in 10 Gateway C failover-only after the first pick, the rest fail over in listed order model remap — before the rule runs model: X remap match, percent: 20 20% 80% Gateway C upstream_model: Y base rule the split above, model X
Top: a 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.
Remaps ride along, they don't replace A rule with zero targets still returns 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 systemone key, 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 answers 400. Jev aliases are translated per host, so a remap to jev-latest works 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_remaps on PUT /api/v1/keys/:id/routing (or routing on POST /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_routing tool. 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 remap badge (expand a row for the attempt path).
  • X-FreeRouter-Attempts counts 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 remap badge.
  • GET /v1/models ignores remaps — there's no model in the request to match on.
Next Providers