智能路由

当请求指定的模型不可用时，智能路由会改用相近的模型来响应，而不是返回错误。即使发生故障，你的应用也能继续运行，无需编写任何重试代码。自动模式支持对话和图像模型。语音模型仅在你自行指定备选模型时才会切换，视频模型则不会切换。

工作原理

1. 每个请求都会先发往你指定的模型。大多数问题在这一步就能解决：如果某条访问路径卡住或报错，系统会先通过其他路径重试，你不会感知到这一过程。
2. 只有当模型本身无法响应（所有路径均失败，或没有可用路径）时，智能路由才会介入。
3. 系统会按顺序尝试备选模型，每个模型都采用相同的自愈机制，直到有模型响应。
4. 响应会注明实际使用的模型（响应体中的 model，以及 x-zurelay-model 和 x-zurelay-routed-from 响应头），并按该模型的价格计费。

只有在尝试过指定模型的所有访问路径后，系统才会尝试备选模型，确保仅在指定模型确实无法响应时才切换。如果所有尝试都很快失败，系统会对指定模型和各备选模型再试一次，之后才返回错误。已知不可用的模型会直接跳过。

启用方式

密钥可选择以下设置之一:

按请求设置

备选模型列表

在 model 之外传入 models：最多指定三个备选模型，当 model 不可用时按顺序尝试，不受密钥设置或请求头影响。该列表不会发送给模型。OpenAI Python SDK 通过 extra_body 传入。图像和语音请求也支持该列表；以表单提交的图像编辑请求则通过 models 字段传入（重复该字段，或使用一个逗号分隔的列表）。

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)

请求头

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

优先级从高到低依次为：请求的 models、请求头、密钥设置、工作区默认设置。

备选模型的适用条件

• 模型类型相同。 对话模型只能使用对话模型作为备选，图像模型只能使用图像模型，语音模型只能使用语音模型。“其他所有模型”规则（*）可以列出多种类型；每个请求只使用与自身类型相同的模型。
• 能读取你发送的内容。 包含 PDF 或视频的请求只会转发给能读取这些内容的备选模型。如果没有符合条件的模型，系统会返回错误，而不是给出忽略文件内容的回答。
• 密钥有权使用。 不在密钥允许使用的模型范围内的备选模型会被跳过。
• 兼容当前端点。 使用 /v1/messages 时，备选模型均为 Claude 模型。
• 请求本身有效。 如果模型拒绝请求（例如参数无效、提示词过长、拒绝绘制提示词中的内容或拒绝朗读文本），系统不会重新路由：备选模型也会拒绝这类请求。

图片

自动模式下，图像请求会优先使用同系列模型（GPT Image 2.5 Sunburst 切换到 Flare，Nano Banana Pro 切换到 Nano Banana 2.1），且只会切换到绘图质量相近的模型。在你指定的尺寸下，自动选择的备选模型费用不会超过原模型的 1.5 倍。自定义规则和请求的 models 列表不受此限制。无论哪种方式，都需满足以下条件:

• 尺寸和宽高比相同。 Nano Banana 模型对 size 和 aspect_ratio 的解析方式相同。GPT Image 仅在输出尺寸一致时，才能替代 Nano Banana：1K 正方形（1024x1024）、1K 3:2 或 2:3、2K 正方形、4K 16:9 或 9:16。Nano Banana 仅在能输出完全一致的像素尺寸（1024x1024、2048x2048），或你未指定尺寸时，才能替代 GPT Image。
• 支持你的参考图数量。 备选模型必须能接收你发送的全部参考图（Nano Banana 14 张，GPT Image 16 张）。
• 支持你的选项。 设置透明 background 的请求只会转发给 GPT Image 模型。
• 每次响应只使用一个模型. 当 n 大于 1 时，所有图片都由同一个模型生成。

语音

语音仅根据你设置的规则或请求中的 models 列表切换模型，不会自动切换。所有语音模型都支持相同的音色，因此备用模型会按你指定的 voice 和 instructions 朗读文本。输入和输出 token 响应头对应实际响应的模型。

自动备用模型

实时读取模型目录：各聊天和图像模型在自动模式下使用的备用模型。

注意事项

• 备用模型的费用可能高于或低于你请求的模型。请求日志会显示实际响应的模型及其费用。
• 流式响应也一样：模型开始响应后才会发送内容，每个数据块都会标明该模型。
• 图像和语音响应都包含相同的 x-zurelay-model 和 x-zurelay-routed-from 响应头，图库中的图片也会标注生成它们的模型。
• 视频不会改用其他模型：视频任务始终使用你请求的模型，并持续重新提交，直到生成成功或失败（不收费）。