Models & routing

Model fallbacks

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

Send a fallback list

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": [
    "google/gemini-3.8-flash",
    "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": "google/gemini-3.8-flash"
    },
    {
      "model": "openai/gpt-6-luna"
    }
  ],
  "max_tokens": 256,
  "messages": [
    {
      "role": "user",
      "content": "Explain an API gateway in one sentence."
    }
  ]
}'

How it works

First choicemodel tries first.
Next in lineIf it cannot start, the next model answers.
Locked inOnce output starts, the model stays. See Failover.

Rules

Length: Three distinct models, including model.
Order: model, then the list. Without model, the first entry leads.
Eligibility: In the catalog, allowed on your key and served by a permitted provider.
Not with: minirouter/auto, Auto Free or providerOptions.

Billing

ChargeThe model that answered.
HoldCovers the priciest model until the request settles.
Answering modelNamed in model and x-minirouter-model.

Settings and errors

Prevent overrides: Routing settings can ignore models and fallbacks.
400 invalid_request: Too many models, a repeat, an unknown or disallowed model, or no provider serves them all.

Send a fallback listExamples read your key from MINIROUTER_KEY.

How it works

Rules

Billing

Settings and errors

Send a fallback list