opendunes
Models and routing · 3 min
Copy page ▾

Provider routing

Choose which providers serve your request, and in what order.

  1. Find a model's providers.
  2. Sort or pin them.
  3. Hold the request to what you need.

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.

FieldHolds
sortthe order to try them in: price, throughput, latency or exacto
orderprovider tags, tried in this order
onlyprovider tags; no other provider serves the request
ignoreprovider tags that never serve the request
allow_fallbacksfalse 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:

WriteTries first
anthropic/claude-sonnet-4.5:nitrothe fastest providers
anthropic/claude-sonnet-4.5:floorthe cheapest providers
anthropic/claude-sonnet-4.5:exactothe providers whose tool calls are the most reliable

Suffixes combine. Among :nitro, :floor and :exacto, the last one wins.

Do

Leave allow_fallbacks at true unless one provider is a hard requirement. With false, a provider that is down fails your request.

Don't

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

FieldHolds
max_pricean 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_parameterstrue 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.

Watch out

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.

StatusMeans
400the provider object holds a field it does not know, or a value of the wrong kind
402the balanceBalanceWhat you can spend, in DA.More on Balance and charges → cannot cover the request
404no such model
503no provider meets the routing you asked for