Model Fallbacks

Model fallbacks let you pass an ordered models array (up to 4 slugs) instead of a single model string. If the first model errors or is unavailable, OpenDunes retries the request with the next model in the list — transparently, with no extra code on your side.

How it works#

Replace the "model" field with a "models" array of up to 4 entries. Each entry is a standard provider/model slug. OpenDunes tries them in order until one succeeds.

{
  "models": [
    "anthropic/claude-opus-4.8",
    "anthropic/claude-sonnet-5",
    "openai/gpt-5.4"
  ],
  "messages": [{ "role": "user", "content": "Explain micro-DA in two sentences." }]
}

The response is identical to a normal chat completion — the model field in the response body tells you which model actually answered.

Fallback behavior#

OpenDunes triggers a fallback on the following conditions:

If every model in the list fails, OpenDunes returns the error from the last attempt with the standard error shape.

Streaming and fallbacks#

Fallbacks work with streaming ("stream": true). If the primary model starts streaming and then drops the connection mid-response, OpenDunes does not restart from the fallback — a partial stream is returned as-is. Fallbacks only activate before the first token is sent.

Response headers#

The X-Request-Id header in the response always reflects the final successful attempt. If you need to know which model answered, read the model field in the response JSON.

Pricing (DA)#

Each attempt is billed independently at that model's DA rate — only the attempt that returns a response is charged. Attempts that fail before any tokens are generated cost nothing.

Check per-model DA rates (input/output per million tokens) at GET /api/models/{slug} or in the model catalog.

Using with the OpenAI SDK#

The OpenAI SDK sends whichever value you pass as model. To use fallbacks, pass the models array as an extra body field using the SDK's extra_body / extra_headers escape hatch.

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="anthropic/claude-opus-4.8",       # ignored by OpenDunes when models[] is set
    messages=[{"role": "user", "content": "Hello from Algiers!"}],
    extra_body={
        "models": [
            "anthropic/claude-opus-4.8",
            "anthropic/claude-sonnet-5",
            "openai/gpt-5.4",
        ]
    },
)
print(resp.choices[0].message.content)
print("Answered by:", resp.model)

Note. When models is present, any model field in the same request is ignored. The model field in the response always reflects which model actually handled the request.