调用指南与双路由

适用角色：开发者、组织（顶层用户）、子用户更新日期：2026-07-02

新版控制台为同一个模型提供了两种调用名：带指纹的和不带指纹的，并在「调用指南」页把两者并排展示、一键复制。本文讲清楚这两种调用名分别怎么用、走哪条路由、什么场景用哪个，以及在哪里拿到它们。

一、两种调用名

到控制台「调用指南」页，你会看到当前账户可达的每个分组，其下每个模型都并排给出两种可复制的调用名：

形态	示例	路由行为
带指纹	`5MHXZWKA/gpt-4o`	按指纹"点名"固定路由到该分组
不带指纹（裸模型名）	`gpt-4o`	路由到调用所用 Key 绑定的路由分组

5MHXZWKA 是分组的指纹，gpt-4o 是裸模型名，中间用 / 连接。带指纹的复制按钮仅在该分组已开放指纹时出现。

什么是指纹？指纹是平台为每个路由分组自动分配的一串短字符标识（如 5MHXZWKA），创建后保持不变，你无需手动创建或管理。你可以在控制台「调用指南」页的分组卡片上看到并复制它。指纹的作用是让你在调用时通过 <指纹>/<模型名> 的格式精确指定走哪个分组。

二、网关怎么分流

网关在收到请求时，首先判断 model 字段是否包含指纹前缀（含 /）：

带指纹（如 5MHXZWKA/gpt-4o）：解析指纹，固定路由到该指纹对应的分组
不带指纹（如 gpt-4o）：路由到这把 Key 绑定的路由分组
带指纹：无论你这把 Key 绑定哪个分组，都按指纹"点名"到指定分组，灵活。
不带指纹：走这把 Key 绑定的路由分组，和老版「每 Key 一个分组」行为一致，老客户端零改造。

⚠️ 不带指纹调用时，若这把 Key 未绑定任何路由分组，平台会直接返回 403（裸名不可调用）。遇到这种情况，去「调用指南」改用带指纹调用名，或先在「API 密钥」页为该 Key 绑定路由分组。

选定的渠道不可用时，平台直接返回错误，当前不会自动切换到其他渠道、不做降级兜底。请在客户端做好重试，见错误码与排障。

三、什么场景用哪个

场景	建议
老脚本/老客户端已在跑	用裸模型名，零改造继续用
一把 Key 想临时切到别的分组	用带指纹调用名，点名到目标分组
同一用户多把 Key、各绑不同分组	用裸模型名，各 Key 各走各绑定的分组
不确定调用名怎么写	直接去「调用指南」复制，最稳妥

四、在哪里拿到调用名

登录控制台，左侧导航栏点击「调用指南」进入页面。

页面结构

调用指南页面从上到下依次是：

顶部说明栏：简要介绍调用名的格式规则（<指纹>/<裸模型名>）
搜索框：可按分组名、平台、指纹、模型名搜索，快速定位目标
平台 Tab 栏：按模型供应商（如 Anthropic、OpenAI、Google 等）分 Tab，点击切换只看该供应商的分组；搜索时 Tab 自动隐藏，改为跨全部平台展示结果
专属 / 公开筛选：区分你组织专属的分组和平台公开的分组

分组卡片

每个可用分组显示为一张卡片，包含：

分组名：卡片顶部，如"Claude 官方直连""GPT 高性价比"
计费类型标签：标注该分组是「按量扣余额」还是「订阅制」
指纹前缀：可点击复制整个指纹前缀（如 5MHXZWKA/），格式为 <指纹>/<模型名>
可用模型列表：该分组下所有可调用的模型，每个模型并排两个复制按钮——
- 「裸名」按钮：复制裸模型名（如 claude-sonnet-4-6），调用时走你 Key 绑定的路由分组
- 「指纹」按钮：复制带指纹的调用名（如 5MHXZWKA/claude-sonnet-4-6），调用时固定走该分组。此按钮仅在该分组已开放指纹时出现

操作步骤

进入「调用指南」页
通过平台 Tab 或搜索框找到目标模型
在对应的分组卡片中，点击模型右侧的「裸名」或「指纹」复制按钮
将复制的调用名填入代码中的 model 字段

可调用哪些分组，取决于你账户的可用模型范围（由平台按组织配置）。看不到目标模型时，见管理员手册 · 地区与模型范围。

五、调用示例

两种调用名都用标准 OpenAI 兼容格式，只是 model 字段写法不同。

不带指纹（裸模型名）：

bash

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

带指纹（点名分组）：

bash

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

端点、认证、流式等通用规则见 API 调用基础。API 地址为 https://api.cloudrouter.online，调用前缀为 /v1。

六、常见问题

Q：我必须改用带指纹的调用名吗？ A：不必须。裸模型名继续有效，走这把 Key 绑定的路由分组。带指纹只是多给一种"点名分组"的灵活方式。

Q：带指纹和不带指纹，计费有区别吗？ A：计费按实际命中的分组/渠道定价（以「模型广场」或控制台「购买」页展示为准），与调用名写法本身无关，取决于最终走到哪个分组。

Q：我同一把 Key 用裸名和指纹混着调，可以吗？ A：可以。网关按每次请求的 model 是否带指纹分别判定路由：裸名走 Key 绑定分组，指纹点名到对应分组。

Q：带指纹调用时报"分组不可达"怎么办？ A：说明该指纹对应的分组不在你账户的可用范围内，或该渠道当前不可用。确认可用范围，或联系 CloudRouter，见错误码与排障。

Q：调用指南会同时给出两种调用名吗？ A：会。「调用指南」页每个模型都并排展示「裸名」和「带指纹」两种可复制的 Model ID（带指纹按钮在分组开放指纹时出现），按需复制即可。

联系我们

电子邮箱：support_cloudrouter@clouditera.com
QQ 社群：712273971
平台网址：cloudrouter.online

调用指南与双路由 ​

一、两种调用名 ​

二、网关怎么分流 ​

三、什么场景用哪个 ​

四、在哪里拿到调用名 ​

页面结构 ​

分组卡片 ​

操作步骤 ​

五、调用示例 ​

六、常见问题 ​

联系我们 ​