Key 可调用性查询

在真正调用一个模型之前，你可以先问一句：「我这把 Key，现在能不能调这个模型？」——这就是本页描述的 preflight 接口。

这个接口回答的不是「平台上这个模型存不存在」，而是「你这把 Key、这份余额、这套权限，此刻能不能调它」。两者是不同的问题。

一、接口

GET https://intertoken.ai/v1/v1/models/{model}/preflight
Authorization: Bearer sk-...

用你要查询的那把 Key 自己发起请求——平台不提供「用 A 的凭据查 B 的 Key」这种代查能力，因为那会引入新的越权面。

二、响应

可调用时：

{
  "model": "qwen/qwen3.7-plus",
  "callable": true,
  "checked": ["ip", "auth", "balance", "routing"],
  "not_checked": ["rate_limit", "quota_reservation"],
  "as_of": "2026-08-08T09:40:12Z"
}

不可调用时多一个 reason_code：

{
  "model": "qwen/qwen3.7-plus",
  "callable": false,
  "reason_code": "balance_insufficient",
  "checked": ["ip", "auth", "balance", "routing"],
  "not_checked": ["rate_limit", "quota_reservation"],
  "as_of": "2026-08-08T09:40:12Z"
}

字段	说明
callable	布尔值，准确含义见下方「三、callable 到底承诺了什么」
reason_code	仅 callable: false 时出现，取值来自错误码表
checked	本次判定实际检查过的层，恒定为 ["ip", "auth", "balance", "routing"]（成功或失败都一样，它是能力声明，不是执行轨迹）
not_checked	本次判定没有检查的层，恒定为 ["rate_limit", "quota_reservation"]——见下方说明
as_of	判定发生的时刻，你可以据此判断这个答案有多「新鲜」

三、callable 到底承诺了什么

callable 是一个必要不充分条件：

callable: false  ⇒  现在调用一定会失败        （强承诺，可以依赖）
callable: true   ⇒  静态条件都通过；限流与额度预占等时变条件未检查   （弱承诺）

正确用法是用它提前排除已知不可用的情况，而不是用它替代正常的错误处理——通过了 preflight 之后仍然可能因为限流或并发额度耗尽而调用失败，这在契约范围内，不是缺陷。

四、为什么 not_checked 恒为 ["rate_limit", "quota_reservation"]

这两项本身会消耗你的限流计数额度或占用余额（限流计数需要真实执行一次计数动作，额度预占需要真实锁定一部分余额）。如果 preflight 也去跑这两项，「问一下能不能调」这个动作本身就会消耗你的额度——问得越勤，答案越容易变成「不能」。所以 preflight 结构性地跳过这两项，明确把它们列在 not_checked 里,而不是悄悄略过不说。

五、失败语义

情形	平台承诺什么
preflight 说 false，实际调用也失败	一致——这是设计保证
preflight 说 false，实际调用却成功	不会发生——静态阻断项是硬性拦截
preflight 说 true，实际调用失败于限流或额度预占	在契约范围内，not_checked 已提前说明这两项未检查
preflight 说 true，实际调用失败于已检查过的那几层（IP/鉴权/余额/路由）	属于缺陷，欢迎向平台反馈

六、不做什么

• 不提供代查：只能用某把 Key 自己查自己，不支持用一把 Key 查另一把 Key 的可调用性
• 不返回内部细节：reason_code 只使用错误码表里已登记的值，不会暴露供应商名称、内部路由 ID 等信息
• 不做批量查询：如需对多个模型批量判断可调用性，请联系平台评估配额方案
• 不承诺响应时效窗口：as_of 就是判定时刻本身，平台不会给出「N 秒内保证有效」这类承诺——余额可能在下一毫秒被另一次并发调用消耗完