调用指南与路由说明

适用角色：开发者、主用户、子用户更新日期：2026-07-14

本文讲清楚调用时 model 字段该怎么填、请求走哪条路由、以及在哪里获取调用名。

一、基础路由：模型名称调用

绝大多数场景下，你只需要在 model 字段填写模型名称（如 gpt-4o、claude-sonnet-4-6），系统会自动为你选择路由分组。

路由解析优先级

当你使用模型名称调用时，系统按以下顺序逐级查找该模型应走哪个分组，命中即停：

优先级	路由来源	说明
1	Key 绑定的路由分组	如果这把 Key 绑定了分组，模型名称调用走该分组
2	子用户默认路由配置	子用户自己配置的"模型 X 走分组 Y"
3	主用户默认路由配置	主用户配置的默认路由
4	平台默认路由	平台为该模型预设的默认分组

以上任一层命中即走该分组，不再往下查找
如果四层都未命中，调用会被拒绝
选定的渠道不可用时，平台直接返回错误，不自动切换渠道、不降级、不兜底

默认路由配置

主用户和子用户可以为每个模型名称指定默认走哪个分组，无需在每把 Key 上单独绑定。配置入口在控制台中，可逐个模型设置，也可按供应商批量设置。

使用记录中会显示每次调用的路由来源标识（Key 绑定分组 / 子用户默认 / 主用户默认 / 平台默认），方便排查路由走向。

默认模型配置页面：

默认模型配置

如果默认路由配置的分组已被下架或不再包含该模型，调用会报错，不会静默回退到其他分组。遇到此情况需重新配置默认路由。

二、进阶路由：分组标识调用（需开启）

平台提供了一种进阶路由能力——分组标识路由。开启后，你可以在模型名前加上分组标识前缀（如 5MHXZWKA/gpt-4o），精确"点名"走某个分组，不受 Key 绑定和默认路由配置的影响。

开启条件

分组标识路由默认关闭，需要同时满足两个条件才能生效：

平台开启了全局分组标识路由开关
主用户在自己的账户中开启了分组标识路由

两个开关都开启后，该组织及其下所有子用户可使用分组标识调用名。

分组标识调用名格式

<分组标识>/<模型名称>

示例：5MHXZWKA/gpt-4o

5MHXZWKA 是分组的标识——平台为每个路由分组自动分配的短字符标识，创建后保持不变
gpt-4o 是模型名称
调用时，请求固定路由到该分组标识对应的分组，与 Key 绑定的分组和默认路由配置无关

「调用指南」页面

控制台左侧菜单的「调用指南」入口始终可见。该页面按分组列出当前可用的模型。分组标识路由开启后，每个模型并排提供模型名称和带分组标识两种复制按钮：

模型名称按钮：复制模型名称（如 claude-sonnet-4-6），走基础路由
分组标识按钮：复制带分组标识的调用名（如 5MHXZWKA/claude-sonnet-4-6），走分组标识路由

页面支持按供应商 Tab 切换、关键词搜索、专属/公开分组筛选。

分组标识路由未开启时，调用指南页不显示分组标识调用名，带分组标识前缀的调用会被拒绝。模型名称也可在模型广场（无需登录）或通过 /v1/models API 获取。

调度分组白名单（仅主用户可配）

开启分组标识路由后，主用户还可为 Key 配置「调度分组白名单」，约束分组标识调用能到达哪些分组。此为进阶项，子用户不可配置，多数场景无需设置。

三、完整路由解析链路

平台在收到请求时，首先判断 model 字段是否包含分组标识前缀（含 /）：

model 字段含 "/" ?
├── 是（如 5MHXZWKA/gpt-4o）
│   └── 分组标识路由已开启？
│       ├── 是 → 解析分组标识，路由到对应分组
│       └── 否 → 拒绝（分组标识路由未开启）
└── 否（如 gpt-4o）
    └── 按优先级查找：Key 绑定分组 → 子用户默认 → 主用户默认 → 平台默认
        ├── 命中 → 路由到该分组
        └── 全部未命中 → 拒绝

四、什么场景用哪种

场景	建议
老脚本 / 老客户端已在跑	用模型名称，零改造继续用
不想每把 Key 都绑分组	配置默认路由，所有 Key 模型名称调用自动走默认分组
一把 Key 想临时切到别的分组	开启分组标识路由后，用带分组标识的调用名点名
不确定调用名怎么写	用模型名称最简单；需要精确控制分组时再考虑分组标识

五、调用示例

模型名称（基础路由）：

curl YOUR_API_BASE_URL/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "你好"}]
  }'

带分组标识（分组标识路由，需开启）：

curl YOUR_API_BASE_URL/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "5MHXZWKA/gpt-4o",
    "messages": [{"role": "user", "content": "你好"}]
  }'

端点、认证、流式等通用规则见 API 调用基础。

六、常见问题

Q：我必须开启分组标识路由吗？ A：不必须。大多数场景用模型名称就够了，系统会按 Key 绑定分组或默认路由配置自动解析。分组标识路由是进阶能力，按需开启。

Q：带分组标识和模型名称，计费有区别吗？ A：计费按实际命中的分组定价，与调用名写法无关，取决于最终走到哪个分组。

Q：同一把 Key 用模型名称和分组标识混着调，可以吗？ A：可以（分组标识路由开启时）。平台按每次请求的 model 是否带分组标识分别判定路由。

Q：带分组标识调用时报"分组不可达"怎么办？ A：说明该分组标识对应的分组不在你账户的可用范围内，或该渠道当前不可用。确认可用范围或联系平台。

Q：默认路由配置了但调用报错？ A：检查配置的分组是否仍包含该模型——分组下架或模型移除后，对应的默认路由配置会失效，需重新设置。

Q：使用记录里"路由来源"是什么？ A：标识本次调用的路由是通过哪层解析命中的（分组标识 / Key 绑定分组 / 子用户默认 / 主用户默认 / 平台默认），方便排查路由走向。

Q：分组标识路由关闭后，已有的带分组标识调用会怎样？ A：会被拒绝。关闭分组标识路由后，所有带分组标识前缀的调用都不再被识别，需改用模型名称。