模型可用性

这个端点报的是什么

网关会周期性地真调一遍当前在售模型背后的上游路由，并把结果记下来。本端点返回这份观测，并按你的 API Key 的授权范围裁剪。

它回答的是「这个模型现在能不能被服务」，不是「这个模型有没有配好、有没有启用」。一个模型可以启用着、发布着、目录同步也正常，而每一次调用都失败——本端点正是为暴露这种情况而存在。

设计消费逻辑时请记住两条：

• 这是观测结果，不是 SLA。 检测延迟等于巡检周期（响应里的 probe_interval_sec）。两次巡检之间坏掉的模型，这里报的仍是上一次的结论。
• unknown 不等于「不可用」。 它表示平台没有近期观测：巡检关着、这个模型还没被探过、或最近一次巡检已超过两倍周期。请把 unknown 当作可用，不要因此拦截。

鉴权

服务端调用。使用 Authorization: Bearer <API_KEY> 鉴权，请把 Key 保存在自己的后端。

读取可用性

curl https://u-token.ai/v1/models/availability \\
  -H "Authorization: Bearer sk-YOUR_KEY"

{
  "generated_at": "2026-09-23T09:30:00.000Z",
  "probe_interval_sec": 600,
  "data": [
    {
      "model": "claude-sonnet-5",
      "status": "available",
      "checked_at": "2026-09-23T09:29:41.000Z",
      "channels": [
        {
          "channel": "standard",
          "status": "available",
          "checked_at": "2026-09-23T09:29:41.000Z",
          "recent": "111"
        }
      ]
    },
    {
      "model": "gpt-5.6-terra",
      "status": "degraded",
      "reason": "upstream_5xx",
      "checked_at": "2026-09-23T09:28:02.000Z",
      "channels": [
        {
          "channel": "flex",
          "status": "degraded",
          "reason": "upstream_5xx",
          "checked_at": "2026-09-23T09:28:02.000Z",
          "recent": "011"
        }
      ]
    },
    {
      "model": "kimi-k3",
      "status": "unknown",
      "checked_at": null,
      "channels": [
        { "channel": "standard", "status": "unknown", "checked_at": null, "recent": null }
      ]
    }
  ]
}

状态取值

status 与 reason 都是开放取值。遇到不认识的值必须按 unknown 处理，而不是报错——新增取值不算破坏性变更。

reason 只在状态不是 available 时出现。当前取值：no_upstream（该模型与渠道没有可发货路由）、upstream_5xx、upstream_timeout、upstream_auth、upstream_rate_limited、upstream_unavailable、empty_response、request_error。

recent 是该渠道最近三次巡检结果，新的在前（1 成功、0 失败）；从未探过时为 null。

行集与范围

• 行与渠道与 GET /v1/models 完全一致：同一套授权范围、同一套渠道解析。你的 Key 调不到的模型不会出现在这里。
• 模型级 status 由渠道聚合：任一渠道 available 即 available；全部 unavailable 才 unavailable；全部 unknown 才 unknown；其余为 degraded。
• 结果按平台维度而非按 Key：两把能调用同一模型与渠道的 Key 看到相同状态。巡检使用路由的默认上游凭据，因此配了专属上游账号的 Key 看到的仍是共用路由的状态。
• 媒体模型会出现，但状态恒为 unknown——本期只巡检文本模型路由。

/v1/models 上的 health 字段

GET /v1/models 以可选字段 health 携带同一份观测，一次拉取清单的设备不必再多调一个接口：

没有 health 字段表示「未观测」，不表示「不可用」——请只按 health === "down" 过滤。

用 ETag 轮询

请用 ETag / If-None-Match 轮询，不要定时拉全量。60 秒是一个合适的间隔。

curl -i https://u-token.ai/v1/models/availability \\
  -H "Authorization: Bearer sk-YOUR_KEY" \\
  -H 'If-None-Match: "a7f3c18e"'

ETag 只覆盖模型、渠道、状态与原因的集合，不含 checked_at。所以只要状态集合没变，即使巡检时间戳已经向前走了，也返回 304 Not Modified 且无响应体。

错误

每个响应都带 x-aitoken-request-id，请保留以便支持与对账。