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
- 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.
- Only when the model itself can’t answer (every path failed, or none is available) does smart routing step in.
- It tries the alternatives in order, each with the same self-healing, until one answers.
- The answer tells you which model replied (
modelin the body,x-zurelay-modelandx-zurelay-routed-fromheaders), 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
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 osfrom openai import OpenAIclient = 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
x-zurelay-fallback: off # never reroute this requestx-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
sizeandaspect_ratiothe 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
backgroundonly goes to GPT Image models. - One model per answer. With
nabove 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.
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-modelandx-zurelay-routed-fromheaders, 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.
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.