文档 / API 指南 / 模型、准入与回退

模型、准入与回退

请求体里的 model 填的是平台模型 ID，不是上游厂商的原始模型名。 这一页讲清楚：ID 从哪查、哪些模型你现在能调、调不通时网关会不会自动换一个。

模型 ID 从哪来

模型清单是公开的，不需要鉴权即可查询：

GET /api/v1/user/user/models
200 OK 
{
  "code": 0,
  "message": "ok",
  "data": [
    {
      "id": 12,
      "model_id": "claude-sonnet-5",
      "name": "Claude Sonnet 5",
      "status": "enabled",
      "client_visible": true,
      "rate_multiplier": 1,
      "vendor_code": "anthropic",
      "vendor_name": "Anthropic",
      "forward_model_id": "claude-sonnet-4-5-20250929"
    }
  ]
}

请求里要写的是 model_id（"claude-sonnet-5"）， 而 forward_model_id 是网关转发给上游时用的真名——你不需要关心它， 它会随上游版本变化，写进代码里迟早会失效。

💡
同一个 model_id 可能对应多个厂商

一个平台模型可以挂多条上游链路（不同厂商、不同凭证）。所以列表里同一个 model_id 出现多行是正常的，每行是一条可用链路。 真正走哪条由网关按可用性、限流状态和优先级选择，客户端无需干预。

列表里看不到的模型

只有同时满足下面两个条件的模型才会出现在这个接口里：

有些模型是内部或定向开放的，client_visible 为 false： 列表里看不到，但如果你知道 ID 且有权限，调用是通的。

模型准入限制

部分模型设了准入门槛。判定发生在入口阶段——鉴权之后、路由与计费之前， 不通过就直接返回，不产生任何费用。

限制方式判据等级
不限制任何账号都能调—
认证等级账号的实名认证类型0 未认证 < 1 个人 < 2 企业
套餐等级当前生效订阅的套餐0 无 < 1 PLUS < 2 PRO < 3 PROMAX

判定规则很简单：你的等级 ≥ 模型要求的等级即放行。 限制参数为 0（或负数）时一律放行——这是「配了限制方式但没配门槛」的兜底。

被拒时的返回

403 Forbidden 
{
  "code": 40203,
  "message": "该模型需完成企业认证后使用",
  "error": { "type": "gateway_error", "code": "40203" }
}

错误码统一是 40203，message 会说明差的是哪一档：

要求message
个人认证该模型需完成实名认证后使用
企业认证该模型需完成企业认证后使用
PLUS 套餐该模型需订阅 RouterCode PLUS 后使用
PRO 套餐该模型需订阅 RouterCode PRO 后使用
PROMAX 套餐该模型需订阅 RouterCode PROMAX 后使用
⚠️
BYOK 不豁免准入限制

即使你用自己的厂商凭证（BYOK，平台不扣费），准入限制照样生效。 因为它限制的是模型本身，不是计费来源。

🧭
认证等级只认一份数据

认证等级取自账号资料里的用户类型，与用户中心页面上显示的、模型列表下发用的是同一份数据。 所以不会出现「页面显示已认证、调用却说没认证」这种分裂。 刚通过认证后立即调用即可生效，无需等待缓存过期。

模型回退

账号可以配置一个回退模型。当原模型的所有可用上游链路都失败后， 网关不会直接把错误抛给你，而是改用回退模型再试一次。

先按原模型正常选路

逐条尝试该模型可用的上游链路，这一步与平时无异。

全部失败后取回退模型

读取你配置的回退模型（有短时缓存，改配置后约一分钟内生效）。没配则直接返回原始错误。

用回退模型重新选路

回退模型自己也要过一遍选路与准入判定。成功则正常返回，失败则返回原始错误。

⚠️
限流失败也会触发回退

「原模型被限流」同样算作链路失败，会进入回退——因为链路层的限流计数是 按模型维度记的，换个模型确实可能有额度。 这意味着你可能在完全没察觉的情况下用回退模型完成了一次调用： 响应体里的模型名会如实反映实际使用的模型，对模型有强要求时请校验响应中的模型名。

回退不会改变计费口径——按实际调用的模型的价格计费， 详见 计费、积分与订阅。

查询价格与能力

定价接口除了价格，还会下发模型的能力标签，可以用来判断一个模型支不支持图片输入：

GET /api/v1/user/user/pricing
字段说明
support_features能力标签数组，取值 text / image / audio / video
input_price / output_price每百万 token 的输入/输出单价
cache_input_price / cache_output_price命中缓存时的单价
image_price / video_price按张/按条计价的模型使用
billing_modes该模型支持的计费方式

带上登录态调用时，返回里的 user_rate 是你个人的倍率；匿名调用一律返回 100（原价）。完整字段见 平台管理 API。

常见问题