Routes and routing

One model can be served by several routes with different prices and speeds. Each route has a fixed ID such as fast or cheap; every model page lists its routes and prices.

By default

With no settings, routes are tried in the recommended order. If one fails, the next is tried automatically.

Per request: the route field

Add route to the request body; it applies to that request only:

"route": "fast"                                       only this route
"route": ["fast", "cheap"]                            only these, in this order
"route": { "sort": "price" }                          cheapest first
"route": { "sort": "price", "max_price_usd": 0.05 }   same, skipping routes over $0.05
"route": { "routes": ["fast", "cheap"], "max_price_usd": 0.05 }

Defaults on a key

On the API keys page, open a key's routes and limits to set:

• Sort: the recommended order, cheapest first, or your own order.
• Routes to skip: this key never uses them.
• Exception rules: requests that match (some models, or a parameter such as resolution = 4K) use only the routes you name. The first matching rule applies.
• Maximum price: routes above it are not used.

From strongest to weakest: the request's route → the key's first matching exception rule → the key's sort and skipped routes → the recommended order.

How failover works

• Tasks only move between routes you allow; never to a route outside the list.
• Sorting only decides which route goes first. Nothing else is decided for you.
• A route that can't take these parameters (say, no 4K) is skipped.
• After a move, the task is billed at the new route's price. See Billing and refunds.

Related errors

• route_not_offered: the requested route doesn't offer this model.
• no_route_selected: your settings rule out every route for this model.
• price_above_max: every selected route costs more than your maximum.
• unsupported_parameters: no selected route supports these parameters.