Platform

Smart routing

When the model a request names is down, smart routing answers with a close alternative instead of an error. Your app keeps working through an outage without a line of retry code. Automatic mode covers chat and image models. Speech switches models only when you choose the alternatives yourself, and videos and embeddings never do.

How it works

  1. Every request first goes to the model you asked for. Most problems end here: if one path to the model stalls or errors, the request is retried on another before you see anything.
  2. Only when the model itself can’t answer (every path failed, or none is available) does smart routing step in.
  3. It tries the alternatives in order, each with the same self-healing, until one answers.
  4. The answer tells you which model replied (model in the body, x-zurelay-model and x-zurelay-routed-from headers), and it’s billed at that model’s price.

Every path to the model you asked for gets its turn before an alternative is tried, so you only get another model when yours really can’t answer. If everything failed quickly, the model and its alternatives each get one more try before you see an error. A model known to be down is skipped straight away.

Turning it on

WhereHowApplies to
Workspace defaultSettings → Smart routingEvery key that doesn’t set its own, and the Playground
Per keyAPI keys → Edit → Smart routingRequests with that key
Per requesta models list, or the x-zurelay-fallback headerThat request

A key’s setting is one of:

Workspacedefault
Follow the workspace setting (off unless you turned it on).
Offmode
If the model is down, the request fails with model_unavailable, which you can retry.
Automaticmode
Use our list of close alternatives for each chat and image model (below): the same family and a similar price first. Speech requests stay on the model you asked for.
Custommode
Your own rules: for each model, up to three alternatives in order. A rule for “any other model” (*) covers the rest.

Per request

A list of alternatives

Pass models next to model: up to three alternatives, tried in order if model is down, whatever the key’s setting or the header. It’s never sent to the model. The OpenAI Python SDK sends it through extra_body. Image and speech requests take it too, and an image edit sent as a form takes it as a models field (repeated, or one comma-separated list).

import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.zurelay.com/v1",
api_key=os.environ["ZURELAY_API_KEY"],
)
response = client.chat.completions.create(
model="gpt-6-sol",
messages=[
{
"role": "user",
"content": "Summarize this ticket in one line: ..."
}
],
extra_body={
"models": [
"gpt-6.1-sol",
"gpt-6-astra"
]
},
)
print(response.choices[0].message.content)

The header

Headers
x-zurelay-fallback: off # never reroute this request
x-zurelay-fallback: auto # use the automatic alternatives (chat and image models)

What applies, first to last: the request’s models, then the header, then the key’s setting, then the workspace default.

What alternatives can answer

  • They’re the same kind of model. A chat model’s alternatives are chat models, an image model’s are image models, a speech model’s are speech models. A rule for any other model (*) may list several kinds; each request uses the ones of its own kind.
  • They read what you sent. A request with a PDF or a video only goes to alternatives that read it. If none does, you get the error rather than an answer that ignores your file.
  • The key may use them. Alternatives outside a key’s allowed models are skipped.
  • They speak the endpoint. On /v1/messages, alternatives are Claude models.
  • The request itself is fine. If the model refused the request (a bad parameter, too long a prompt, a prompt it won’t draw or text it won’t speak), it isn’t rerouted: the alternatives would refuse it too.

Images

In automatic mode an image goes first to the same family (GPT Image 2.5 Sunburst to Flare, Nano Banana Pro to Nano Banana 2.1), and only to models that draw about as well. An automatic alternative never costs more than 1.5 times the model you asked for at the size you asked for. Your own rules and a request’s models list have no such limit. Either way:

  • The same size and shape. Nano Banana models read size and aspect_ratio the same way. GPT Image stands in for a Nano Banana size only where both make the same picture: 1K square (1024x1024), 1K 3:2 or 2:3, 2K square, 4K 16:9 or 9:16. Nano Banana stands in for a GPT Image pixel size only when it makes exactly those pixels (1024x1024, 2048x2048), or when you didn’t ask for a size.
  • Your reference images. An alternative must take as many as you sent (Nano Banana 14, GPT Image 16).
  • Your options. A transparent background only goes to GPT Image models.
  • One model per answer. With n above 1, every image comes from the same model.

Speech

Speech switches models only with your own rules or a request’s models list, never in automatic mode. Every speech model speaks the same voices, so an alternative reads your text in the voice you asked for, with your instructions. The input and output token headers are the answering model’s.

Automatic alternatives

Live from the catalog: the alternatives each chat and image model falls back to in automatic mode.

If this model is downAutomatic smart routing tries, in order
Claude Opus 5.5Claude Opus 5→Claude Opus 4.8→Claude Sonnet 5.5
GPT-6.2 AstraGPT-6 Astra→GPT-6.2 Sol→Claude Opus 5.5
GPT-6 AstraGPT-6.2 Astra→GPT-5.6 Sol→GPT-6.1 Sol→Claude Opus 5.5
Claude Sonnet 5.5Claude Opus 5.5→Claude Opus 4.8→Claude Haiku 5.5
Claude Haiku 5.5Claude Haiku 4.5→GPT-6 Luna→Gemini 3.1 Flash-Lite
GPT-6.2 SolGPT-6.1 Sol→GPT-6 Sol→GPT-6.1 Terra
GPT-6.1 SolGPT-6.2 Sol→GPT-6 Sol→GPT-5.6 Terra→GPT-5.6 Sol
GPT-6.1 TerraGPT-6.1 Sol→GPT-6 Sol→GPT-5.6 Terra
GPT-6 SolGPT-6.1 Sol→GPT-5.6 Terra→GPT-5.6 Sol
GPT-6 LunaGPT-5.6 Luna→Gemini 3.1 Flash-Lite→DeepSeek V4.1 Flash
Grok 4.7GPT-6.1 Sol→Gemini 3.7 Flash→GLM-5.3
MiMo V2.6 ProMiMo V2.6 Flash→DeepSeek V4 Pro 0813→GLM-5.3
MiMo V2.6 FlashMiMo V2.6 Pro→DeepSeek V4.1 Flash→Qwen 3.8 Flash
DeepSeek V4.1 Flash 1017DeepSeek V4.1 Flash→DeepSeek V4 Pro 0813→Qwen 3.8 Flash
DeepSeek V4.1 FlashDeepSeek V4 Flash 0731→DeepSeek V4 Pro 0813→Qwen 3.8 Flash
DeepSeek V4 FlashDeepSeek V4 Flash 0731→DeepSeek V4 Pro 0813→Qwen 3.8 Flash
DeepSeek V4 Flash 0731DeepSeek V4.1 Flash→MiMo V2.6 Flash→Qwen 3.8 Flash
DeepSeek V4 Pro 0813DeepSeek V4.1 Flash→GLM-5.3→MiMo V2.6 Pro
Claude Fable 5.2Claude Fable 5.1→Claude Opus 5.5→Claude Opus 5
Claude Fable 5.1Claude Fable 5.2→Claude Fable 5→Claude Opus 5.5
Claude Fable 5Claude Fable 5.2→Claude Fable 5.1→Claude Opus 5.5
Claude Opus 5Claude Opus 4.8→Claude Opus 5.5→Claude Opus 4.7
Claude Opus 4.8Claude Opus 5→Claude Opus 4.7→Claude Opus 5.5
Claude Opus 4.7Claude Opus 4.8→Claude Opus 4.6→Claude Opus 5
Claude Opus 4.6Claude Opus 4.7→Claude Opus 4.8→Claude Opus 5
Claude Haiku 4.5Claude Haiku 5.5→Claude Sonnet 5.5
GPT-5.6 SolGPT-6.1 Sol→GPT-5.6 Terra→GPT-6 Sol
GPT-5.6 TerraGPT-6.1 Terra→GPT-6.1 Sol→GPT-6 Sol
GPT-5.6 LunaGPT-6 Luna→Gemini 3.5 Flash-Lite→DeepSeek V4.1 Flash
Gemini 4 HydrogenGemini 4 Argon→Gemini 3.8 Flash→GPT-6.1 Sol
Gemini 4 ArgonGemini 3.1 Pro→Gemini 3.8 Flash→GPT-6.1 Sol
Gemini 3.1 ProGemini 4 Argon→Gemini 3.8 Flash→GPT-6.1 Sol→Claude Sonnet 5.5
Gemini 3.8 FlashGemini 3.7 Flash→GPT-6.1 Sol→DeepSeek V4 Flash
Gemini 3.7 FlashGPT-6.1 Sol→Gemini 3.5 Flash-Lite→DeepSeek V4 Flash
Gemini 3.5 Flash-LiteGemini 3.1 Flash-Lite→Gemini 3.7 Flash→GPT-5.6 Luna
Gemini 3.1 Flash-LiteGemini 3.5 Flash-Lite→GPT-6 Luna→DeepSeek V4.1 Flash
GLM-5.3GLM-5.2→DeepSeek V4 Pro 0813
GLM-5.2GLM-5.3→DeepSeek V4 Pro 0813
GLM-5.3 FlashGLM-5.3→DeepSeek V4 Flash→Qwen 3.8 Flash
Kimi K3.1 ProKimi K3→GLM-5.3→DeepSeek V4 Pro 0813
Kimi K3.1 Pro HighspeedKimi K3.1 Pro→Kimi K3→GLM-5.3
Kimi K3Kimi K3.1 Pro→Qwen 3.8 Max→GLM-5.3
Qwen 3.8 MaxKimi K3→GLM-5.3→DeepSeek V4 Pro 0813
Qwen 3.8 FlashQwen 3.8 Omni Flash→DeepSeek V4.1 Flash→MiMo V2.6 Flash
Qwen 3.8 Omni FlashQwen 3.8 Flash→Gemini 3.1 Flash-Lite→MiMo V2.6 Flash
MiniMax M3.1 FlashMiniMax M3→DeepSeek V4.1 Flash 1017→Qwen 3.8 Flash
MiniMax M3GLM-5.3→DeepSeek V4 Pro 0813
Step 5 PreviewDeepSeek V4 Pro 0813→GLM-5.3→MiMo V2.6 Pro
Kimi K2.6Kimi K3.1 Pro→GLM-5.3→DeepSeek V4 Pro 0813
Kimi K2.5Kimi K2.6→Kimi K3.1 Pro→GLM-5.3
MiniMax M2.5MiniMax M3→GLM-5.3→DeepSeek V4 Pro 0813
Ministral 3 3BMinistral 3 14B→Qwen 3.8 Flash→DeepSeek V4.1 Flash
Ministral 3 14BMinistral 3 3B→Qwen 3.8 Flash→DeepSeek V4.1 Flash
Nano Banana 2.1Nano Banana Pro→Nano Banana 2→GPT Image 2.5 Flare
Nano Banana ProNano Banana 2.1→Nano Banana 2→GPT Image 2.5 Flare
Nano Banana 2Nano Banana 2.1→Nano Banana Pro→GPT Image 2.5 Flare
Nano Banana 2 LiteGPT Image 2.5 Flare→GPT Image 2.5 Sunburst→GPT Image 2
GPT Image 2.6 FlareGPT Image 2.6 Sunburst→GPT Image 2.5 Flare→GPT Image 2.5 Sunburst
GPT Image 2.6 SunburstGPT Image 2.6 Flare→GPT Image 2.5 Sunburst→GPT Image 2.5 Flare
GPT Image 2.5 FlareGPT Image 2.5 Sunburst→GPT Image 2.6 Flare→GPT Image 2
GPT Image 2.5 SunburstGPT Image 2.5 Flare→GPT Image 2.6 Sunburst→GPT Image 2
GPT Image 2GPT Image 2.5 Flare→GPT Image 2.5 Sunburst→Nano Banana 2.1
Grok Imagine Image 2.0Nano Banana Pro→GPT Image 2.5 Flare→Nano Banana 2.1
FLUX 3 ImageNano Banana Pro→Nano Banana 2.1→GPT Image 2.5 Flare

Things to know

  • An alternative may cost more or less than the model you asked for. Your request log shows the model that answered and its cost.
  • Streaming works the same: nothing is sent until a model is answering, and the chunks name that model.
  • Image and speech responses carry the same x-zurelay-model and x-zurelay-routed-from headers, and images in your library are labeled with the model that made them.
  • Videos aren’t rerouted: a video job stays with the model you asked for, and is resubmitted until it’s made or fails (free).
  • Embeddings aren’t rerouted either: vectors from different models can’t be compared, so another model’s would be wrong for your index. See Embeddings.
Check x-zurelay-routed-from in your logs or monitoring: it’s set only when an alternative answered, so you can see how often a model you depend on was down. The one exception is Zurelay Auto, which sets it to zurelay-auto on every answer.

Questions, or something missing? Ask our support team and we’ll answer by email, usually within a minute.