Model failover

How it works

Every request first goes to your API key's preferred model. If that model's provider fails to serve the request — a network error, a timeout, or an error response from the provider — we automatically retry the request once, this time with the fallback model configured on that key. If the fallback succeeds, your player gets a normal response and never sees the outage.

• Failover is reactive: we try your preferred model on every request and only fall over when it actually fails.
• There is one retry, with your single configured fallback model — not a chain of models.
• It applies to both /v1/chat/completions (text) and /v1/image/generations (images), each with its own fallback setting.
• If you don't configure a fallback model, a request to a model that's down simply fails (see status codes) instead of falling over.

Configuring a fallback model

Fallback is set per API key, so different keys (or different game builds) can have different backups. On your dashboard, open a key and use the Automatic fallback model selector:

• The key's Text page sets the fallback used for chat/text generation.
• The key's Image page sets the fallback used for image generation.
• Choose None to disable failover for that key.

Pick a fallback served by a different provider than your preferred model when you can — that way an outage of one provider is covered by the other. You can see which provider backs each model, and its current health, on the status page.

Billing

You are only charged for the model that actually generated the response. If your preferred model fails and the fallback succeeds, you pay the fallback model's rate — the failed attempt costs you nothing. If every model fails and the request returns 502, no credits are charged at all.

Detecting when a fallback was used

The model field in the response tells you which model produced it. If it doesn't match your key's preferred model, a fallback was used — a useful signal to log if you want visibility into provider outages.

{
  "choices": [ ... ],
  "model": "gemini-2.5-flash",   // served by your fallback model
  "usage": { "total_tokens": 87 }
}

Status codes

Provider status page

We track each model provider's health from live traffic and publish it, along with a rolling uptime history, on our status page. Check it if you're seeing failovers or errors, or to decide which model makes the best fallback for your preferred one.