OmniRail · Router

Auto (best)

auto:best

LanguageRouted

Send model: "auto:best" and OmniRail picks the model for each request from the live catalog. The highest quality tier that can serve the request, then the cheapest model in it.

The choice is deterministic and free: no extra model call, no routing fee. You pay the list price of the model that answered, and the response tells you which one it was and why.

Four ways to pick

auto: Reads the request: short chat goes to a good-value model, long prompts, code, tools or many turns go to a stronger one. Cheapest capable model at that level.
auto:cheap: The cheapest capable model for this request, never below quality tier 2.
auto:fast: Low-latency model families first (Flash, Haiku, mini…), then the cheapest of them.
auto:best: The highest quality tier that can serve the request, then the cheapest model in it.

How it chooses

Needs. Images in the messages require vision, tools require tool calling, response_format requires JSON or structured outputs, PDFs (native reading) require file input, audio requires audio input, and the context must hold the prompt plus max_tokens.
Your limits. Optional route: max_price_per_mtok (USD per 1M tokens, on the higher of the input and output list prices), allow and deny id patterns such as "anthropic/*". Deny wins.
Never. Previews and experiments, moving aliases, classifiers, image or audio generators, and variants that share prompts with the provider.
Rank. A curated quality tier per model family, then the estimated price of this request, then the newest model. Same request, same catalog, same pick.
Fallbacks. If the chosen model fails before any output (provider error, rate limit, provider timeout or no endpoint), the next candidate runs (up to 2 more models). A failed attempt costs nothing; its hold is released before the next one is reserved. Streams switch only before the first byte reaches you.

Quality tiers

Families the router knows. A model it has never seen counts as tier 2 until the table learns it.

Tier 4 · frontier: Claude Opus / Fable · GPT Astra · GPT Pro · Gemini Pro
Tier 3 · strong: Claude Sonnet · GPT Sol / Terra / Codex · GPT-5.x · OpenAI o-series · Gemini Pro (legacy) · Gemini Flash · DeepSeek Pro / R1 · Qwen Max · Mistral Large · Kimi K3 · GLM-5
Tier 2 · good value: Claude Haiku · GPT mini · GPT Luna · GPT OSS · GPT-4 (legacy) · Gemini (legacy) · Gemini Flash-Lite · Grok fast / mini · Grok (legacy) · DeepSeek Flash · Qwen Flash · Llama 4 Scout · Mistral Small · GLM Flash / Air
Tier 1 · small: Gemma · models of 14B parameters or fewer

Use it

POST /api/v1/chat/completions · MCP chat · Playground · reference

curl https://omnirail.org/api/v1/chat/completions \
  -H "Authorization: Bearer $OMNIRAIL_KEY" -H "Content-Type: application/json" \
  -d '{"model":"auto:best","messages":[{"role":"user","content":"Hello"}],
       "max_tokens":300, "route":{"max_price_per_mtok":20,"deny":["x-ai/*"]}}'

The answer carries the routed model in model, the X-OmniRail-Routed-Model header and a routing object (in the first chunk of a stream):

{
  "model": "<the model that answered>",
  "choices": [ … ],
  "usage": { "cost": …, "promo_discount": … },
  "routing": {
    "requested": "auto:best",
    "chosen": "<model id>",
    "reason": "…why this model…",
    "candidates": [ /* top 3: id, tier, input_per_million,
                     output_per_million, estimated_usd */ ],
    "fallbacks": [ { "model", "status", "error" } ]
  }
}