Routing & fallback

How a model is chosen, and what happens on a provider outage.

routing_strategy

Every endpoint accepts model (optional) and routing_strategy (default "auto"):

manual — uses exactly the provided model. model_not_found error if it doesn't exist in the catalog.
auto — quality/cost weighted score (quality x 0.7, normalized cost penalty x 0.3) among the available models of the category. A cheaper provider can therefore win over a slightly better but more expensive provider.
best_quality — sorts by quality score only, descending.
cheapest — sorts by average price only, ascending.
fastest — sorts by observed average latency, ascending.

json

{ "model": "claude-opus-5", "routing_strategy": "manual" }

Automatic fallback

Except in manual, if the first chosen candidate fails (provider outage, timeout, 5xx error), the request is automatically retried with the next candidate in the ranking — completely transparently to you. The call only fails if all compatible candidates have failed (503 all_providers_unavailable).

Provider health status

Each provider has a continuously monitored status: healthy, degraded, or down. A down provider is excluded from the ranking (open circuit); a degraded provider remains usable but as a last resort. Queryable via:

bash

GET /v1/status

Model catalog

The full list of models available per category, with prices and capabilities, is freely queryable (no AI call, free):

bash

GET /v1/models?category=text

A multi-category provider (e.g. OpenAI for text and image) shares a single health status across its categories — an outage specific to one category also affects that provider's other categories in automatic routing.