Provider routing
Choose which providers serve your request, and in what order.
A request that names no routing goes to the cheapest provider that serves its model first. Everything below is for when that is not what you want.
1. Find a model's providers
One model can be served by several providers. One model's providers lists them for a model: each entry holds a tag, the provider's name for routing, and the request fields it honours.
2. Sort or pin them
Add a provider object to the request. Each field narrows or orders the providers tried.
| Field | Holds |
|---|---|
sort | the order to try them in: price, throughput, latency or exacto |
order | provider tags, tried in this order |
only | provider tags; no other provider serves the request |
ignore | provider tags that never serve the request |
allow_fallbacks | false to stop at the providers you named, true to let the next one serve when they fail |
sort also takes an object, {"by": "latency", "partition": "none"}: partition is model to sort within each model, or none to sort every provider together, across the models you named.
import json
import os
import urllib.request
API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/chat/completions"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "Write a one-line welcome for a bakery in Tlemcen."
body = {
"model": MODEL,
"provider": {"sort": "latency", "allow_fallbacks": True},
"messages": [{"role": "user", "content": PROMPT}],
}
request = urllib.request.Request(
ADDRESS,
data=json.dumps(body).encode(),
headers={
"Authorization": "Bearer " + API_KEY,
"Content-Type": "application/json",
},
)
with urllib.request.urlopen(request) as response:
reply = json.load(response)
print(reply["choices"][0]["message"]["content"])
print(reply["usage"]["cost"])A pinned provider is charged at that provider's price, not the cheapest one's: usage.cost is the charge of the provider that served.
When you only want one ordering, a suffix on the model name says it in a word:
| Write | Tries first |
|---|---|
anthropic/claude-sonnet-4.5:nitro | the fastest providers |
anthropic/claude-sonnet-4.5:floor | the cheapest providers |
anthropic/claude-sonnet-4.5:exacto | the providers whose tool calls are the most reliable |
Suffixes combine. Among :nitro, :floor and :exacto, the last one wins.
Leave allow_fallbacks at true unless one provider is a hard requirement. With false, a provider that is down fails your request.
Don't confuse it with Fallbacks. allow_fallbacks moves on to another provider of the same model; models moves on to another model.
3. Hold the request to what you need
| Field | Holds |
|---|---|
max_price | an object of numbers, none below zero: the most you will pay, in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges → per million tokens, for each meter the model has. A provider above it is not tried |
require_parameters | true to try only the providers that honour every field of your request |
data_collection | "deny" to try only the providers that do not keep your data |
The settings of your account bind every request. A request's own provider wins field by field, and may add a restriction, but never lift one the account holds.
When no provider meets what you asked for, the request fails with a 503. Loosen one field, or name more providers.
Errors
The body says why. What to do on every status: Errors and retries.
| Status | Means |
|---|---|
| 400 | the provider object holds a field it does not know, or a value of the wrong kind |
| 402 | the balanceBalanceWhat you can spend, in DA.More on Balance and charges → cannot cover the request |
| 404 | no such model |
| 503 | no provider meets the routing you asked for |