Key 可调用性查询

The guide below is in Chinese.

使用准备调用模型的同一把 Key 检查权限、余额和当前路由。检查结果不预占额度,实际调用仍需处理限流等错误。

一、接口

Shell command
curl "https://staging-dp.taotoken.io/v1/models/ENCODED_MODEL_ID/preflight" -H "Authorization: Bearer $TP_API_KEY"

把模型 ID 中的斜杠编码为 %2F,填入 ENCODED_MODEL_ID。

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

二、响应

可调用时:

JSON
{
  "model": "MODEL_ID",
  "callable": true,
  "checked": ["ip", "auth", "balance", "routing"],
  "not_checked": ["rate_limit", "quota_reservation"],
  "as_of": "2026-08-08T09:40:12Z"
}

不可调用时多一个 reason_code:

JSON
{
  "model": "MODEL_ID",
  "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判定发生的时刻,你可以据此判断这个答案有多「新鲜」

reason_code: tier_unavailable:这把 Key 在控制台「扣费顺序」里开启了「只使用所选规格」,而所选规格此刻没有可用货源,且这把 Key 名下没有生效中的套餐。此时真实调用也会返回同一个 tier_unavailable,可以加选规格或关闭该开关。名下有生效中套餐时按套餐判定,不受这个开关影响。

三、callable 到底承诺了什么

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

Code
callable: false  ⇒  在判定时存在已知阻断项,请按 reason_code 排查
callable: true   ⇒  在判定时检查通过;仍需处理限流与额度预占

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

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

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

五、失败语义

比较 as_of 和实际调用时间。余额、权限和路由可能在两次请求之间变化。预检通过而实际调用失败时,先看错误码,再区分限流、预占和已检查的项目。

六、不做什么

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

下一步

获取当前模型 ID · 按协议调用