GrooRoute Pro 服务档位与后缀路由:自动换档规则与请求级档位选择
GrooRoute Pro 把模型供给分成经济、均衡、高质量、自营四个服务档位。同一个模型在不同档位上的价格与可用供给不同,实时价格见模型页,本页不写价格数字。档位既可以在 API Key 上统一设置,也可以在单次请求的 model 字段里用冒号加后缀临时指定。
四个档位与后缀取值
请求里写后缀时,四个档位对应下面四个小写标识;请求分配到四个档位之一时,响应头 X-GrooRoute-Tier 返回的也是这四个值之一:
| 档位 | 定位 | 后缀写法 |
|---|---|---|
| 经济 | 适合轻量任务与批量处理。 | economy |
| 均衡 | 日常开发,兼顾成本与响应。 | balanced |
| 高质量 | 适合重视稳定性的任务。 | high_quality |
| 自营 | 由平台直接运营的供给。 | self_operated |
后缀请用上表四个小写值;default 作为均衡档的兼容别名也能用,新配置不建议使用。大写或中文档位名不算档位后缀。
方式一:在 API Key 上设置(自动与固定档位)
在控制台「API 密钥」创建或编辑密钥时,可以把密钥设为自动或单一档位:
- 自动(推荐日常使用):以所选档位为上限,当该档位暂时没有可用供给时,网关会按从高到低的顺序改用更便宜的档位,绝不会越级调用更贵的档位。
- 单一档位:这把 Key 发出的请求只走该档位,不自动向更便宜的档位回退。
方式二:单次请求加模型名后缀
不改 Key 配置、只想让某一次请求固定走指定档位时,在模型 ID 后面拼上冒号和上表「后缀写法」一列的值(例如 <模型 ID>:economy)。公开模型清单不说明每个模型在哪个档位上架,所以下面的示例不写具体模型:把模型 ID 换成模型页上在该档位上架的模型。
curl https://grooroute.com/v1/chat/completions \
-H "Authorization: Bearer $GROOROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"<模型 ID>:economy","messages":[{"role":"user","content":"Hello"}]}'
- 带后缀的请求只在后缀指定的档位调用,不会自动换档;上游收到的是去掉后缀后的模型名。
- 请求分配到四个档位之一时,响应头里才有
X-GrooRoute-Tier,写明本次请求实际命中的档位标识(上表四个值之一);请求没有落在这四个档位上时,响应里没有这个头。 - OpenAI SDK、Codex CLI、Claude Code 和 OpenCode 的模型字段同样支持这一写法;在接入文档页选中档位后,生成的配置片段会自动带上对应后缀。
与档位后缀相关的报错码
带后缀的请求无法在指定档位完成时,网关不会静默改走别的档位,而是返回明确的 error.code:
| error.code | 原因与处理办法 |
|---|---|
TIER_NOT_ALLOWED_FOR_KEY | 指定的档位不在这把 Key 允许的档位里(自动 Key 的档位链可以跳过中间档位,单一档位 Key 只允许它那一档)。换用允许该档位的 Key,或去掉后缀。 |
TIER_MODEL_NOT_OFFERED | 指定的档位没上架这个模型,而这把 Key 的其他档位上架了。到模型页查看该模型开放的档位,改用其他档位后缀或去掉后缀。 |
TIER_SESSION_BOUND | 当前严格会话已经绑定在另一个档位的渠道上。新开会话,或改回原档位。 |
TIER_CONNECTION_LOCKED | 当前 Responses WebSocket 连接已经在服务另一个档位。新建连接后再切换档位。 |
TIER_SUFFIX_UNSUPPORTED | 在网关无法改写模型名的请求里写了档位后缀(例如 multipart 表单上传、任务插件类接口),返回 400。去掉后缀,改用 Key 上的档位设置。 |
如果这把 Key 的所有档位都没上架这个模型,返回 403 MODEL_NOT_ALLOWED_FOR_GROUP;如果这个模型名在任何分组都不存在(多为拼写错误),返回 404 model_not_found,核对模型名拼写即可,不需要改 Key 的档位。
如果该档位上架了这个模型但暂时没有可用渠道,网关返回 503 model_not_found,可查看服务状态。更多状态码说明见常见报错排查,计费与额度规则见怎么计费。
常见问题
选了自动的 Key 会自动升到更贵的档位吗?
不会。自动 Key 只在所选上限档位及更便宜的档位里按从高到低的顺序回退,不会越级调用更贵的档位。
单次请求指定了档位后缀,该档位不可用时会自动换档吗?
不会。带后缀的请求只在指定的档位调用;无法完成时直接返回错误码,去掉后缀即可恢复按 Key 的设置调用。
怎么看某次请求实际走了哪个档位?
请求分配到四个档位之一时,接口响应头里有 X-GrooRoute-Tier,写的是本次请求实际命中的小写档位标识;请求没有落在这四个档位上时没有这个响应头。
返回 TIER_NOT_ALLOWED_FOR_KEY 或 TIER_MODEL_NOT_OFFERED 是什么意思?
TIER_NOT_ALLOWED_FOR_KEY 表示当前 Key 不允许使用后缀指定的档位;TIER_MODEL_NOT_OFFERED 表示指定的档位没上架这个模型,而这把 Key 的其他档位上架了;如果这把 Key 的所有档位都没上架这个模型,返回的是 403 MODEL_NOT_ALLOWED_FOR_GROUP;如果这个模型名在任何分组都不存在(多为拼写错误),返回的是 404 model_not_found。
最后更新: