Routing failover

Use routing failover when one Tresor request may move from one route to another inside the router. Use retries when your client or SDK sends a new request after an error response or a connection failure.

Automatic routing and explicit chat failover are separate mechanisms. A bare model key stays within one model key and lets the router pick a concrete provider and region route. Chat failover is a separate ordered route list; it can keep the same model key or move to a different one.

If you are deciding how specific the primary model should be, see Routing. Shorter selectors usually give Tresor more eligible routes and therefore higher availability.

Two different mechanisms

If you need backoff, retry budgets, or timeout guidance, see Retries and transient errors.

How routing failover works

At a high level, the router follows a simple sequence:

1. It determines the preferred route from your request.
2. It builds the set of routes it is allowed to use. For chat completions, that means the primary model plus any explicit failover entries you provided. Each of those routes can be pinned or automatic, but automatic resolution still stays within that route's model key. For transcriptions, there is no client-provided failover list. Automatic routing only considers concrete routes for the requested transcription model key.
3. It tries the preferred route first.
4. If that route cannot be used or fails before the request completes, the router moves to the next eligible route.
5. If one route succeeds, the response reports the requested route via tresor.requested_route, the actual route via tresor.routed_model, and tresor.failover is true if the router had to leave the preferred route.
6. If no eligible route succeeds, the request fails.

That is the stable contract clients should rely on. The exact health checks and internal routing heuristics can evolve over time.

Chat completions: explicit routing failover

POST /v1/chat/completions accepts a Tresor-only failover field. It is an ordered list of alternative routes that the router may try if the primary route is unavailable. Each entry can be a pinned compound model ID or a shorter canonical selector such as gemma-4-31b, eu/gemma-4-31b, or nearai/gemma-4-31b.

curl https://api.tresor.co/v1/chat/completions \
  -H "Authorization: Bearer $TRESOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eu/privatemode/kimi-k2.6",
    "messages": [{"role": "user", "content": "Summarize this contract."}],
    "failover": [
      "global/chutes/kimi-k2.6",
      "global/tinfoil/deepseek-v4-pro"
    ]
  }'

In OpenAI SDKs, pass Tresor-only request fields through extra_body:

from openai import OpenAI

client = OpenAI(
    api_key="tr-...",
    base_url="https://api.tresor.co/v1",
)

resp = client.chat.completions.create(
    model="lux/tresor/kimi-k2.5",
    messages=[{"role": "user", "content": "Summarize this contract."}],
    extra_body={
        "failover": [
            "global/chutes/kimi-k2.6",
            "global/tinfoil/deepseek-v4-pro",
        ]
    },
)

Chat failover rules

• The router tries the primary model first, then each failover entry in order.
• Each failover entry must parse like the primary route. That includes pinned compound IDs and shorter canonical selectors such as gemma-4-31b, eu/gemma-4-31b, or nearai/gemma-4-31b.
• Maximum 5 failover entries.
• The selected route can have different pricing from the primary route. By listing a route, you accept that route's pricing if the router uses it.
• If you want a different model as the backup, you must list that model explicitly in failover. A bare model key on its own never changes the model key.
• Some OpenAI-compatible clients, coding harnesses, and agent tools do not expose Tresor-only request body fields. In those environments you may not be able to send failover at all.
• If all listed routes are unavailable, the request fails with 503.

Use GET /v1/models?detail=true to inspect available providers, regions, and pricing before building a failover list.

What the response tells you

Tresor reports the route that actually served the request:

• tresor.requested_route: the canonical primary route you asked for
• tresor.routed_model: the final compound model ID used
• tresor.failover: true when chat completions had to leave the primary top-level model and use a route from your failover list

When you use automatic routing such as a bare model key, the router may still resolve or retry concrete candidates for that same model key while tresor.failover stays false. tresor.requested_route and tresor.routed_model can differ in that case. That is automatic resolution inside one model key, not explicit failover.

That metadata appears on the non-streaming response object, or on the final SSE chunk for streaming responses.

Audio transcriptions: router-managed route switching

POST /v1/audio/transcriptions does not accept a client-provided failover array.

Instead, transcription routing depends on how specific your model is:

• If you send an explicit compound route such as eu/privatemode/whisper-large-v3, the router either uses that route or fails.
• If you send a bare model key such as whisper-large-v3, the router may choose another eligible concrete route for that same model key before giving up.

Automatic transcription routing does not change the model key for you. If you ask for whisper-large-v3, the router does not silently move the request to voxtral-small-24b. If you need a different model, send a different request.

When that happens, the response exposes both tresor.requested_route and tresor.routed_model, and tresor.failover tells you whether the router had to leave the first eligible concrete route for that same model key.

If you need predictable pricing, provider choice, or residency, pin an explicit compound route instead of relying on automatic resolution.

Choosing routes deliberately

• Prefer the same model_key across your primary and alternative chat routes unless you explicitly want different behavior.
• Only include alternative routes whose provider, region, and price you are willing to accept.
• Reserve retries for transient transport or HTTP failures. Routing failover does not replace client-side retry logic.

See also

• Chat completions reference
• Audio transcriptions reference
• Models
• Retries and transient errors