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.
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
}'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
- 01First choice
modeltries first. - 02Next in lineIf it cannot start, the next model answers.
- 03Locked inOnce output starts, the model stays. See Failover.
Rules
| Rule | Detail |
|---|---|
| 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. |
| Shared provider | Every model must share a provider qualified for your request. Incompatible lists are rejected before dispatch. |
| Not with | minirouter/auto, Auto Free or providerOptions. |
Billing
- ChargeThe model that answered.
- HoldCovers the priciest model until the request settles.
- Answering modelOn a stream, read
modelfrom the chunks.Named inmodelandx-minirouter-model.
Settings and errors
| Case | Result |
|---|---|
| Prevent overrides | Routing settings can ignore models and fallbacks.Those responses carry x-minirouter-overrides: ignored. |
400 invalid_request | Too many models, a repeat, an unknown or disallowed model, or no provider serves them all. |