普通用户教程
常见问题处理
遇到问题时，不要一上来重装客户端、重建账号、重置所有配置。按这篇从上到下排查，通常能很快定位。
先判断问题发生在哪一层
Pixel API 调用链路可以拆成 5 层：
客户端 -> Base URL -> API Key -> 分组/账号 -> 上游模型任何一层出错，最终都可能表现为“没有回复”。排查时要先看错误信息。
快速检查清单
先做这 8 个检查：
- API Key 是否复制完整。
- 请求头是否是
Authorization: Bearer sk-...。 - Base URL 是否填成页面显示的地址。
- API Key 是否绑定了分组。
- 账户余额是否足够。
- 模型名是否属于当前分组或账号白名单。
- 客户端是否重启过。
- “使用记录”里有没有失败请求。
401：密钥无效或没有认证
常见原因：
- API Key 少复制了一段。
- 前后多了空格或换行。
- 写成了
Authorization: sk-...，缺少Bearer。 - 客户端里填错了 Key。
- Key 被删除或停用。
处理方式：
- 回到“API 密钥”页面。
- 找到正在使用的 Key。
- 确认状态是“活跃”。
- 重新点击复制。
- 重新粘贴到客户端。
- 完全重启客户端后再试。
正确格式是：
Authorization: Bearer sk-你的密钥403：权限、分组或 IP 限制不允许
常见原因：
- API Key 没绑定分组。
- 当前用户没有该分组权限。
- Key 开了 IP 白名单，但你当前网络出口 IP 不在白名单。
- Key 已过期。
- 余额不足或分组准入条件不满足。
处理方式：
- 打开“API 密钥”。
- 看 Key 的分组列是不是“无分组”。
- 如果是，点击分组列重新选择。
- 编辑 Key，检查“IP 限制”。
- 编辑 Key，检查“密钥有效期”。
- 去“充值/购买”或个人资料确认余额。
第一次接入时，建议关闭 IP 限制和有效期，等跑通后再逐项开启。
429：请求太多或并发过高
常见原因：
- 客户端同时开了太多请求。
- Key 设置了 5 小时、1 天、7 天速率限制。
- 分组或账号本身并发有限。
- 账号广场里单用户并发较低。
处理方式：
- 降低客户端并发。
- 稍等几十秒再试。
- 检查 API Key 的“速率限制”。
- 如果使用账号广场，换一个单用户并发更高的账号。
- 如果经常触发，考虑更换分组或联系管理员调整。
模型不存在或模型不可用
常见原因：
- 模型名拼错。
- 你选择的分组不支持这个模型。
- 账号广场里该账号没有把这个模型放入白名单。
- 客户端默认模型和 Pixel API 支持模型不一致。
处理方式：
- 打开“可用渠道”，复制页面里的模型名。
- 如果使用账号广场，复制账号卡片里的可用模型。
- 把客户端里的模型名改成完全一致。
- 重启客户端。
不要凭感觉把模型名改成“差不多”的名字。模型名必须精确匹配。
客户端仍然走旧地址
表现：
- 你明明改了 Base URL，但 Pixel API 使用记录没有新增请求。
- 客户端报的是官方接口错误。
- 改配置后没有任何变化。
处理方式：
- 完全退出客户端。
- 关闭所有相关终端。
- 检查是否有多个配置文件。
- 检查环境变量是否只在当前终端生效。
- 重新打开终端。
- 重新启动客户端。
Windows PowerShell 里设置的 $env:... 只对当前窗口有效。关掉窗口后就失效。如果想长期生效，需要写入系统环境变量或客户端配置文件。
用 PowerShell 能通，客户端不通
这说明 Pixel API 本身、API Key、余额和分组大概率正常。问题在客户端配置。
重点检查：
- 客户端 Base URL 有没有带错
/v1。 - 客户端是否支持你选择的接口类型。
- 客户端模型名是否写死。
- 客户端是否需要单独设置 provider。
- 客户端是否被 CC-Switch 或其他配置管理工具覆盖。
建议先在 API Key 页面点“使用密钥”，复制页面生成的对应客户端配置。
使用记录里没有请求
如果客户端报错，但使用记录里完全没有请求，说明请求可能没有到 Pixel API。
排查：
- Base URL 是否还是官方地址。
- 网络代理是否拦截。
- 客户端是否没有读取新配置。
- API Key 是否填到了错误 provider。
- 请求是否发到了另一个站点地址。
如果使用记录里有失败请求，说明请求到达了 Pixel API，再按状态码和错误信息处理。
账号广场加入失败
常见提示和处理：
| 提示 | 原因 | 处理 |
|---|---|---|
| 没有账号模式 API Key | 你还没创建绑定账号模式分组的 Key | 去“API 密钥”创建 OpenAI账号模式 或 Anthropic账号模式 Key |
| 请选择 API Key | 账号卡片上没有选 Key | 在卡片下拉框选择账号模式 Key |
| 余额低于最低要求 | 你的余额没达到号主设置的最低余额 | 充值或换一个最低余额更低的账号 |
| 空闲退出设置有误 | 空闲退出不是正整数，或超过 10080 分钟 | 填 10、30、60 这类正整数 |
| 账号配置正在编辑中 | 号主正在修改账号参数 | 等编辑结束或换账号 |
收到回复但扣费不符合预期
先看“使用记录”和“余额流水”。
重点看：
- 请求模型是不是你以为的模型。
- API Key 是不是你以为的 Key。
- 分组是不是你选择的分组。
- 是否使用了账号广场。
- 是否产生小时费预扣。
- 是否满足低消并退回小时费。
账号广场里，请求费用和小时费是两条不同逻辑。短时间只发很少请求时，低消未达标可能导致小时费不退。
提供给管理员的信息
如果你需要找管理员协助，不要只说“不能用”。请提供：
- 大概发生时间。
- API Key 名称，不要发完整密钥。
- 使用的客户端。
- Base URL。
- 模型名。
- 错误截图或错误文本。
- 使用记录里的请求 ID 或失败记录。
不要把完整 API Key、账号凭证、OAuth JSON、收款码发到公开聊天里。