模型与用量

模型选择

以当前 /v1/models 返回值为准选择模型。

为什么先查模型列表

模型可用性由 API Key、分组和当前上游状态共同决定。先调用 GET /v1/models，再从返回结果中选择模型；不要把教程截图、聊天记录或旧配置里的模型名当作长期契约。

同一账户下的两把 Key 如果属于不同分组，看到的模型列表也可能不同。客户端报“模型不存在”时，第一步不是猜别名，而是用发生问题的那把 Key 重新查询。

查询当前可用模型

bash

curl --fail-with-body --show-error https://suoxie.codes/v1/models \
  -H "Authorization: Bearer <API_KEY>"

Windows PowerShell 中建议明确调用 curl.exe：

powershell

curl.exe --fail-with-body --show-error https://suoxie.codes/v1/models `
  -H "Authorization: Bearer <API_KEY>"

把 <API_KEY> 替换为准备给目标客户端使用的完整 Key。成功时返回 HTTP 200 和一个 data 数组：

json

{
  "object": "list",
  "data": [
    {
      "id": "<MODEL>",
      "object": "model"
    }
  ]
}

实际模型数量和其他字段会变化。复制其中一个完整 id，包括大小写、连字符和版本后缀；不要复制展示名称，也不要自行删除后缀。

按任务选择

先确认客户端使用哪种接口：Codex 优先使用 Responses API，旧客户端可能只支持 Chat Completions，Anthropic-compatible 客户端使用 Messages。
在 https://suoxie.codes/model-plaza 查看当前展示的模型与价格信息，再以 /v1/models 对这把 Key 的返回结果做最终可用性确认。
第一次验证选择一个满足接口要求的模型，使用短输入、非流式请求和较小输出。
最小请求成功后，再比较输出质量、延迟、上下文需要和实际费用。

“更大”或“更新”的模型不一定最适合每个任务。批量任务应先用代表性样本测量成功率、延迟和费用，不要直接把一次聊天体验当成生产结论。

放入请求

将刚复制的 id 原样放入 model：

bash

curl --fail-with-body --show-error https://suoxie.codes/v1/responses \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"<MODEL>","input":"Reply with OK","store":false}'

成功标志： 请求返回 HTTP 200，响应中的模型信息与目标一致，并且用量页出现对应记录。

模型不可用时

现象	优先处理
`/v1/models` 返回 401	检查 Bearer 格式、Key 是否完整及是否已撤销
列表为空或没有目标模型	核对 Key 分组和账户状态，选择列表中真实存在的模型
列表中存在但请求仍为 403	检查端点能力、分组权限和账户限制
客户端提示 model not found	检查客户端是否保存了旧模型名、增加了前缀或使用了另一把 Key
偶发 429 或 5xx	读取响应正文和 `Retry-After`，有限退避；不要改模型名反复碰撞

如果 cURL 成功而客户端失败，模型和 Key 通常没有根本问题，应回到客户端检查 Base URL、协议类型和缓存配置。

上线注意事项

不把可用模型列表永久写死为唯一来源；至少在发布前重新查询。
模型可见不等于每种能力都受支持，文本、工具、图片和流式输出需要分别做最小验证。
不在日志中记录完整 API Key，也不要把真实 Key 放进前端代码或 Git。
模型价格、能力和可用性可能调整，最终以当前控制台和实时响应为准。

下一步

模型确认后阅读对应的 Responses API、Anthropic Messages 或 Chat Completions，上线前完成检查清单。

为什么先查模型列表 ​

查询当前可用模型 ​

按任务选择 ​

放入请求 ​

模型不可用时 ​

上线注意事项 ​