常见问题
这里收的是接入过程中最常见的问题。建议优先按 Key、分组、模型名和协议入口这四条线去定位。
FAQ 的阅读方式
如果你现在遇到的是具体报错，优先按 Key、分组、模型名、入口协议这四条线去排，而不是先怀疑客户端。
为什么我已经有 Key 了，调用还是报错？
最常见原因不是 Key 本身无效，而是：
- 没有绑定分组
- 分组已停用
- 分组平台和你请求的协议不匹配
先回后台确认 Key 的分组，再用模型列表接口做一次最小自检。
文档站地址和 API Base URL 是同一个吗？
不是。
- 文档站：
https://puaai.xyz/docs - API Base URL：
https://puaai.xyz
应该走 /v1/messages 还是 /v1/chat/completions？
看你的客户端和分组平台：
- Claude / Anthropic 兼容客户端，优先
/v1/messages - OpenAI 兼容客户端，优先
/v1/chat/completions或/v1/responses - Gemini SDK / CLI 这类原生客户端，才走
/v1beta/*
为什么 /v1/models 有结果，但正式请求还是失败？
说明至少鉴权和分组是通的，但还可能卡在：
- 具体模型名填错
- 这个入口不支持你当前平台
- 某个能力当前上游不支持
- 请求体格式与协议不匹配
比如 OpenAI 分组通常走 /v1/chat/completions 或 /v1/responses，不要直接拿它去打 /v1/messages。
什么时候才需要看 /v1beta/models？
只有明确接 Gemini SDK / CLI 这类原生客户端时才需要。普通 OpenAI 兼容、Claude 兼容、Codex、Claude Code 场景，优先看 /v1/models。
社区里说的“刀”“倍率”“缓存计费”是什么意思？
它们通常是在描述站内余额和站内计费口径：
- “刀”通常指站内额度，不等于银行实时汇率下的真实美元
- “倍率”通常指当前分组在官方基准价之上叠加的计费系数
- “缓存计费”通常指输入、缓存读取、缓存创建被拆开单独计费
更完整的说明见 。
Antigravity 分组和普通分组有什么区别？
Antigravity 是一个特殊平台：
- 可能有专用入口
- 可能有模型映射
- 在某些场景下会参与混合调度
所以它最不适合靠“记住一个固定模型名”去接，最好每次都先查当前模型列表。
可以公开查询 Key 用量吗？
可以，站点提供了公开查询页：
https://puaai.xyz/key-usage
如果我要上线自己的实例，文档要改哪里？
最少需要改两类内容：
- 文档站配置里的站点地址、标题和品牌文案
- 页面正文里的
https://puaai.xyz示例
如果你沿用当前工程，这些内容都集中在 frontend/docs 目录里，后续维护会比手写单页轻松很多。