模型与路由

模型名语法、变体、降级链，以及单次请求就能声明的路由偏好。

模型名语法#

plain

provider/model[:variant][,provider/model[:variant]]*

写法	含义
`anthropic/claude-fable-5`	基本形式。
`anthropic/claude-fable-5:nitro`	带变体：吞吐优先。
`anthropic/claude-fable-5,openai/gpt-5-mini`	逗号降级链：前者不可用时自动降级到后者。

大小写不敏感，服务端归一化成小写后匹配。
可以传别名，也可以省略厂商前缀（claude-fable-5）。别名存在歧义时解析结果不确定，因此生产环境建议使用完整模型名。
变体可以叠加，从右往左识别（m:free:nitro 两个都生效）；认不出的后缀原样留在 slug 里，所以带日期版本号的 org/model:2024-05-13 不会被误拆。
主模型加兜底最多 4 个，按顺序尝试，任一成功即返回；超出的静默忽略。
模型已下线返回 model_not_found；标记为将下线（deprecated）且配了替代模型时，替代模型会被自动追加到降级链末尾。
本次实际使用的模型以响应头 X-AiRouter-Model 为准。响应体中的 model 不保证是标准 slug：非流式为上游返回的标识，流式则回显传入的原文。

变体#

变体	作用
`:nitro`	吞吐优先，等价于 `provider.sort = throughput`。
`:floor`	价格优先，等价于 `provider.sort = price`。
`:free`	只用价格为 0 的线路（按零价筛选，而不是按分组名）。配额受限、限流更严。
`:online`	保留后缀，当前不改变路由行为。后缀会被正确解析，不影响模型名匹配。
`:thinking`	保留后缀，当前不改变路由行为。开启思考请使用 `reasoning` 字段，见对话补全。

目前真正影响路由的只有前三项。后两项为兼容 OpenRouter 的写法而保留，不会导致请求失败。

降级链#

降级链可以写在 model 里（逗号形式），也可以写成 models 数组，还可以写在 provider.models 上。三者不是互斥的：网关按 model 逗号链 → models → provider.models 的顺序合并去重，主模型加兜底总共最多 4 个。实际尝试了几次看响应头 X-AiRouter-Attempts。

json

{  "model": "anthropic/claude-fable-5",  "models": ["openai/gpt-5-mini"],  "messages": [{ "role": "user", "content": "hello" }]}

切换模型的前提是本次尚未产生任何输出；响应流一旦开始输出便不再切换。
值得换模型的错误有两类：这个模型此刻走不通（no_candidate / model_not_found / model_not_allowed），以及可重试的上游错误。参数错、鉴权错、余额不足不会触发降级。
allow_fallbacks: false 会同时关掉换线路与换模型。

路由偏好 provider#

这是本平台相对「只做转发」的网关的核心差异：你可以在单次请求里声明怎么选线路，而不是只能接受平台默认策略。

`provider` 只在 OpenAI 对话体里生效

写在 POST /v1/chat/completions（以及同样识别该扩展的图像等 OpenAI 协议请求）里才会被解析。写在 /v1/messages 上会被当成未知字段转发给上游，通常会被上游拒绝并返回 400。要用路由偏好就走 chat，或把降级链写进 model 的逗号形式。详见对话 · Anthropic 协议。

orderstring[]: 显式尝试顺序（分组 code 或供应商名）。列表里的排最前，其余候选按 sort 排在后面；配合 allow_fallbacks: false 时，不在列表里的线路会被直接剔除。
onlystring[]: 白名单，硬过滤。不在名单里的线路完全不会被使用。
ignorestring[]: 黑名单。与 only 都是硬过滤，可以同时给；同一条线路两边都命中时以剔除为准。
allow_fallbacksboolean: 默认 true。设为 false 时只尝试第一个候选，失败即返回——仅在需要确定本次使用的分组（如 A/B 对比）时才关闭它。
require_parametersboolean: 默认 false。设为 true 时只选支持你所传全部参数的线路，而不是静默忽略不支持的参数。
sortstring: price / throughput / latency / balanced（默认 balanced）。
max_priceobject: 价格上限，按 prompt / completion 分别给（USD / 百万 token 的字符串）。超过上限的线路被剔除。
max_retriesinteger: 本次最多尝试几条线路。默认 3，且只能往小调（平台设有上限）；存成路由策略时取值范围 0–5。
zdrboolean: 只使用承诺零留存的线路。
data_collectionstring: allow（默认）或 deny。deny 会剔除可能用于训练的线路。
regionsstring[]: 限定区域：hk / sg / us / cn。
quantizationsstring[]: 限定权重精度，如 fp16 / bf16 / fp8。

生效优先级与执行顺序#

合并是字段级整体覆盖，不是数组求并集——你写的 order 一定是最终生效的顺序。

plain

请求体 provider  >  :变体  >  API Key 的分组模式 / 绑定策略  >  平台默认

这一层是什么	它给出的偏好
平台默认	`sort = balanced`，允许降级。
API Key 的分组模式	价格优先 → `sort = price`；稳定优先 → `sort = throughput`，且只走高可用等级的线路；指定分组 → `only` 锁定该分组并关闭降级；绑定策略 → 使用该策略中保存的整套偏好。
`:变体`	`:nitro` / `:floor` 改 `sort`，`:free` 把价格上限压到 0。
请求体 `provider`	优先级最高，逐字段覆盖上面几层。

硬过滤：only / ignore / zdr / data_collection / regions / quantizations / require_parameters / max_price / 模型能力。
健康过滤：熔断中的线路被剔除。
排序：按 sort 排。
order 覆盖：给了 order 就把它列出的排到最前。
同分档内按权重加权随机选取。
逐个尝试，直到成功或候选耗尽（受 max_retries 与 allow_fallbacks 约束）。

`only` 加 `allow_fallbacks: false` 很容易得到 no_candidate

名单中的线路一旦熔断便不再有候选。生产环境建议 only 至少写入两个分组。排查时请查阅调用日志中的路由轨迹：其中记录了每条线路被哪个条件筛除，据此逐条放宽即可。

列出可用模型#

GET /v1/models 返回 OpenAI 兼容的模型列表，需携带 API Key（否则 401）。结果已按 Key 白名单与上下架过滤，列表里的模型都能调用。本端点不打上游、不扣费，也不限流。响应不含价格；价格与端点明细见模型广场。

bash

curl https://ogrouter.ai/v1/models \  -H "Authorization: Bearer $AIROUTER_API_KEY"

字段	说明
`id`	标准 slug，请求里的 `model` 填这个。
`object`	固定为 `model`。
`owned_by`	模型厂商。
`created`	固定为 `0`。模型目录不提供创建时间。
`context_length`	上下文窗口（token）。
`max_completion_tokens`	单次最大输出（token）。
`modalities`	模态列表，例如 `["text"]`、`["text","video"]`。

模型与路由

模型名语法、变体、降级链，以及单次请求就能声明的路由偏好。

模型名语法#

plain

provider/model[:variant][,provider/model[:variant]]*

写法	含义
`anthropic/claude-fable-5`	基本形式。
`anthropic/claude-fable-5:nitro`	带变体：吞吐优先。
`anthropic/claude-fable-5,openai/gpt-5-mini`	逗号降级链：前者不可用时自动降级到后者。

大小写不敏感，服务端归一化成小写后匹配。
可以传别名，也可以省略厂商前缀（claude-fable-5）。别名存在歧义时解析结果不确定，因此生产环境建议使用完整模型名。
变体可以叠加，从右往左识别（m:free:nitro 两个都生效）；认不出的后缀原样留在 slug 里，所以带日期版本号的 org/model:2024-05-13 不会被误拆。
主模型加兜底最多 4 个，按顺序尝试，任一成功即返回；超出的静默忽略。
模型已下线返回 model_not_found；标记为将下线（deprecated）且配了替代模型时，替代模型会被自动追加到降级链末尾。
本次实际使用的模型以响应头 X-AiRouter-Model 为准。响应体中的 model 不保证是标准 slug：非流式为上游返回的标识，流式则回显传入的原文。

变体#

变体	作用
`:nitro`	吞吐优先，等价于 `provider.sort = throughput`。
`:floor`	价格优先，等价于 `provider.sort = price`。
`:free`	只用价格为 0 的线路（按零价筛选，而不是按分组名）。配额受限、限流更严。
`:online`	保留后缀，当前不改变路由行为。后缀会被正确解析，不影响模型名匹配。
`:thinking`	保留后缀，当前不改变路由行为。开启思考请使用 `reasoning` 字段，见对话补全。

目前真正影响路由的只有前三项。后两项为兼容 OpenRouter 的写法而保留，不会导致请求失败。

降级链#

json

{  "model": "anthropic/claude-fable-5",  "models": ["openai/gpt-5-mini"],  "messages": [{ "role": "user", "content": "hello" }]}

切换模型的前提是本次尚未产生任何输出；响应流一旦开始输出便不再切换。
值得换模型的错误有两类：这个模型此刻走不通（no_candidate / model_not_found / model_not_allowed），以及可重试的上游错误。参数错、鉴权错、余额不足不会触发降级。
allow_fallbacks: false 会同时关掉换线路与换模型。

路由偏好 provider#

这是本平台相对「只做转发」的网关的核心差异：你可以在单次请求里声明怎么选线路，而不是只能接受平台默认策略。

`provider` 只在 OpenAI 对话体里生效

orderstring[]: 显式尝试顺序（分组 code 或供应商名）。列表里的排最前，其余候选按 sort 排在后面；配合 allow_fallbacks: false 时，不在列表里的线路会被直接剔除。
onlystring[]: 白名单，硬过滤。不在名单里的线路完全不会被使用。
ignorestring[]: 黑名单。与 only 都是硬过滤，可以同时给；同一条线路两边都命中时以剔除为准。
allow_fallbacksboolean: 默认 true。设为 false 时只尝试第一个候选，失败即返回——仅在需要确定本次使用的分组（如 A/B 对比）时才关闭它。
require_parametersboolean: 默认 false。设为 true 时只选支持你所传全部参数的线路，而不是静默忽略不支持的参数。
sortstring: price / throughput / latency / balanced（默认 balanced）。
max_priceobject: 价格上限，按 prompt / completion 分别给（USD / 百万 token 的字符串）。超过上限的线路被剔除。
max_retriesinteger: 本次最多尝试几条线路。默认 3，且只能往小调（平台设有上限）；存成路由策略时取值范围 0–5。
zdrboolean: 只使用承诺零留存的线路。
data_collectionstring: allow（默认）或 deny。deny 会剔除可能用于训练的线路。
regionsstring[]: 限定区域：hk / sg / us / cn。
quantizationsstring[]: 限定权重精度，如 fp16 / bf16 / fp8。

生效优先级与执行顺序#

合并是字段级整体覆盖，不是数组求并集——你写的 order 一定是最终生效的顺序。

plain

请求体 provider  >  :变体  >  API Key 的分组模式 / 绑定策略  >  平台默认

这一层是什么	它给出的偏好
平台默认	`sort = balanced`，允许降级。
API Key 的分组模式	价格优先 → `sort = price`；稳定优先 → `sort = throughput`，且只走高可用等级的线路；指定分组 → `only` 锁定该分组并关闭降级；绑定策略 → 使用该策略中保存的整套偏好。
`:变体`	`:nitro` / `:floor` 改 `sort`，`:free` 把价格上限压到 0。
请求体 `provider`	优先级最高，逐字段覆盖上面几层。

硬过滤：only / ignore / zdr / data_collection / regions / quantizations / require_parameters / max_price / 模型能力。
健康过滤：熔断中的线路被剔除。
排序：按 sort 排。
order 覆盖：给了 order 就把它列出的排到最前。
同分档内按权重加权随机选取。
逐个尝试，直到成功或候选耗尽（受 max_retries 与 allow_fallbacks 约束）。

`only` 加 `allow_fallbacks: false` 很容易得到 no_candidate

列出可用模型#

bash

curl https://ogrouter.ai/v1/models \  -H "Authorization: Bearer $AIROUTER_API_KEY"

字段	说明
`id`	标准 slug，请求里的 `model` 填这个。
`object`	固定为 `model`。
`owned_by`	模型厂商。
`created`	固定为 `0`。模型目录不提供创建时间。
`context_length`	上下文窗口（token）。
`max_completion_tokens`	单次最大输出（token）。
`modalities`	模态列表，例如 `["text"]`、`["text","video"]`。