Flux RouterDocumentation

flux-auto vs pinning a model

When to let FluxRouter route with flux-auto and when to pin a flux-pinned-* model id for determinism, capability guarantees, and reproducibility.

You set the model on every request with the model field. With Flux you have a choice: let flux-auto pick a model for you, or pin a specific model so the same one answers every time. This page helps you decide.

What is the difference?

  • flux-auto routes each request to a model sized for it. You do not name a model; Flux picks one. Best when you want good results across a mix of requests without managing model selection. See How smart routing works.
  • Pinning means passing a flux-pinned-* alias so one exact backing model serves the request every time. You give up automatic right-sizing in exchange for a guarantee about which model you get.

Both go through the same metered gateway on the same key, so pinning does not change how you authenticate or bill.

When should I pin a model?

Pin when you need a property that only a specific model can guarantee:

  • Determinism and reproducibility. If you are running evals, regression tests, or anything where the same input must hit the same model, pin it. With flux-auto the routing decision is made per request; pinning removes that variable.
  • Capability guarantees. If your request needs a specific capability (for example a particular model's strength on a task, or a feature only some models support), pin a model you know supports it rather than relying on the route.
  • Output consistency. Different models have different styles and formats. If you have tuned prompts against one model's behavior, pin it so that behavior does not change underneath you.
  • Long context. If you need a large context window, pin a long-context model. See Context windows and long inputs.

When should I use flux-auto?

Use flux-auto (or a tier alias) when you want Flux to right-size each request and you do not need a guarantee about the exact model:

  • Mixed workloads where some requests are simple and some are hard.
  • Cost-sensitive work where you want cheap requests to land on cheap models automatically.
  • General assistant, chat, and content tasks where any capable model is fine.

How do I pin a model?

Pass a flux-pinned-* alias as the model. Everything else about the request stays the same.

bash
curl https://api.fluxrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-pinned-...",
    "messages": [{ "role": "user", "content": "Run this regression prompt." }]
  }'

The authoritative list of flux-pinned-* ids is GET /v1/models. For the full catalog and what each model is good at, see Models.

Can I confirm which model answered?

Yes. Read the X-Flux-Model response header to see which model served the request, and X-Flux-Routed to see whether Flux changed your requested model. When you pin, X-Flux-Routed should be false. See Transparency headers.