Provider Routing

Most models on OpenDunes are served by more than one upstream provider. By default, OpenDunes picks the provider automatically. Provider routing gives you explicit control over how it selects among them.

Available now in the dashboard. Set your account routing preferences at Settings → Routing (/dashboard/settings/routing):

• Provider sort — Balanced (default), Lowest price, Throughput, or Latency.
• Allow fallbacks — fall back to the next provider on failure (on by default).
• Require all parameters — only route to providers that support every parameter in your request.

These apply to your chat and API traffic (applied as the request's provider routing object). Per-request overrides via the provider body field are described below.

How providers work#

When you request a model like google/gemini-2.5-pro, several upstream providers may be able to serve it. OpenDunes maintains a live provider registry per model — availability, observed latency, and per-token cost in DA. The provider routing object in your request body lets you override the default selection logic.

Specifying providers#

Pass a provider object alongside your model:

{
  "model": "google/gemini-2.5-pro",
  "provider": {
    "order": ["ProviderA", "ProviderB"],
    "allow_fallbacks": true
  },
  "messages": [{ "role": "user", "content": "Summarize the news in Arabic." }]
}

Fields#

Sorting providers automatically#

When you don't have a preference for a specific provider but want to optimize for a dimension, set sort instead of order:

{
  "model": "meta-llama/llama-4-maverick",
  "provider": { "sort": "price" },
  "messages": [{ "role": "user", "content": "Draft a short email in French." }]
}

Pinning providers#

Use only to restrict a request to providers that meet your requirements — for example, to enforce data residency for Law 18-07 compliance:

{
  "model": "anthropic/claude-sonnet-5",
  "provider": {
    "only": ["ProviderA"]
  },
  "messages": [{ "role": "user", "content": "Analyze this contract." }]
}

Pinning a single provider also prices the request at that provider's real per-token DA rate.

Note. If none of the pinned providers can serve the model, the request fails rather than falling back elsewhere. Leave at least one viable provider in the set.

Pricing (DA)#

Provider routing can affect the DA cost of a request. Providers priced differently for the same model will yield different per-token rates. The X-Balance-Available header in the response always reflects your balance after the actual provider's cost is deducted.

Check which providers are available for a model and their per-token DA rates via GET /api/models/{slug}.

Using with the OpenAI SDK#

Pass the provider object as an extra body field:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://opendunes.com/api/v1",
    api_key=os.environ["OPENDUNES_API_KEY"],
)

resp = client.chat.completions.create(
    model="google/gemini-2.5-pro",
    messages=[{"role": "user", "content": "What is 2 + 2?"}],
    extra_body={
        "provider": {
            "sort": "latency",
            "allow_fallbacks": True,
        }
    },
)
print(resp.choices[0].message.content)