Models & routing

Model fallbacks

List up to three models. If one cannot start a response, the next one answers.

Send a fallback listExamples read your key from MINIROUTER_KEY.

Chat Completions and Responses take models. Messages takes fallbacks.

Chat Completions
curl https://api.minirouter.sh/v1/chat/completions \
  -H "Authorization: Bearer $MINIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-6-sol",
  "models": [
    "openai/gpt-6-luna"
  ],
  "messages": [
    {
      "role": "user",
      "content": "Explain an API gateway in one sentence."
    }
  ],
  "max_tokens": 256
}'
Messages
curl https://api.minirouter.sh/v1/messages \
  -H "Authorization: Bearer $MINIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
  "model": "openai/gpt-6-sol",
  "fallbacks": [
    {
      "model": "openai/gpt-6-luna"
    }
  ],
  "max_tokens": 256,
  "messages": [
    {
      "role": "user",
      "content": "Explain an API gateway in one sentence."
    }
  ]
}'

How it works

  1. 01First choicemodel tries first.
  2. 02Next in lineIf it cannot start, the next model answers.
  3. 03Locked inOnce output starts, the model stays. See Failover.

Rules

RuleDetail
LengthThree distinct models, including model.
Ordermodel, then the list. Without model, the first entry leads.
EligibilityIn the catalog, allowed on your key and served by a permitted provider.
Shared providerEvery model must share a provider qualified for your request. Incompatible lists are rejected before dispatch.
Not withminirouter/auto, Auto Free or providerOptions.

Billing

  • ChargeThe model that answered.
  • HoldCovers the priciest model until the request settles.
  • Answering modelOn a stream, read model from the chunks.Named in model and x-minirouter-model.

Settings and errors

CaseResult
Prevent overridesRouting settings can ignore models and fallbacks.Those responses carry x-minirouter-overrides: ignored.
400 invalid_requestToo many models, a repeat, an unknown or disallowed model, or no provider serves them all.