模型与路由

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

模型名语法#

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 写法的请求不至于直接 404。

降级链#

降级链可以写在 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#

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

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（平台上限，GATEWAY_MAX_RETRIES），只能往小调；存成路由策略时取值范围 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` 且只走 `-of` / `-vip` 两档 SLA；指定分组 → `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 真正能调的模型：已下线的不返回，受该 Key 模型白名单限制的也不返回——列表里有的就一定调得通。这条端点不打上游、不花钱，因此不限流。

bash

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

字段	说明
`id`	标准 slug，就是请求里 `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 写法的请求不至于直接 404。

降级链#

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#

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

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（平台上限，GATEWAY_MAX_RETRIES），只能往小调；存成路由策略时取值范围 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` 且只走 `-of` / `-vip` 两档 SLA；指定分组 → `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://ai.oceango.hk/v1/models \  -H "Authorization: Bearer $AIROUTER_API_KEY"

字段	说明
`id`	标准 slug，就是请求里 `model` 该填的值。
`owned_by`	模型厂商。
`created`	恒为 `0`。目录没有创建时间，填时间戳会让每次响应都不一样，破坏客户端缓存。
`context_length`	上下文窗口（token）。
`max_completion_tokens`	单次最大输出（token）。
`modalities`	支持的模态，如 `["text"]`、`["text","video"]`。

这里没有价格。价格、可用率与端点明细在模型广场，那是同一份目录的完整视图。