卡皮巴拉 API 使用教程

Appearance

常见问题处理 ​

遇到问题时，不要一上来就重装客户端、重建 API Key、重置所有配置。先按这篇从上到下排查，通常能更快定位是哪一层出了问题。

kapibalaAPI 的调用链路可以简单拆成：

text
客户端 -> 请求地址 -> API Key -> 分组/权限 -> 模型

任何一层出错，最终都可能表现为“没有回复”或“请求失败”。排查时先看错误信息，再动配置。

快速检查清单 ​

先做这 8 个检查：

  1. API Key 是否复制完整，前后没有空格或换行。
  2. API Key 是否填在客户端的密钥字段里。
  3. 请求地址是否填写为 https://kapibala.asia 或 https://kapibala.asia/v1。
  4. 当前客户端是否要求带 /v1。
  5. API Key 是否绑定了正确分组。
  6. 账户余额是否足够。
  7. 模型名是否属于当前分组支持的模型。
  8. 使用记录里有没有新增请求或失败记录。

如果这 8 项里有一项不确定，先不要继续改其它地方。

401：密钥无效或没有认证 ​

401 通常和 API Key 或认证格式有关。

常见原因：

  • API Key 少复制了一段。
  • 前后多了空格或换行。
  • 把 API Key 填到了请求地址字段。
  • 请求头写成了 Authorization: sk-...，缺少 Bearer。
  • Key 已经被删除、停用或重新生成。

处理方式：

  1. 回到 API Key 页面。
  2. 找到正在使用的 Key。
  3. 确认 Key 状态是启用或可用。
  4. 重新点击复制按钮。
  5. 重新粘贴到客户端的 API Key 字段。
  6. 完全退出并重新打开客户端后再测试。

正确的请求头格式是：

text
Authorization: Bearer sk-你的密钥

403：权限、分组或限制不允许 ​

403 通常说明请求已经带上了 Key，但当前 Key 不允许这样调用。

常见原因：

  • API Key 没有绑定分组。
  • 当前账号没有对应分组权限。
  • Key 开启了 IP 限制，但当前网络出口 IP 不在白名单。
  • Key 已过期。
  • 账户余额不足。
  • 当前模型不允许在这个分组里调用。

处理方式：

  1. 打开 API Key 页面。
  2. 检查这个 Key 是否绑定了分组。
  3. 检查 IP 限制是否开启。
  4. 检查有效期是否已经过期。
  5. 检查账户余额。
  6. 换成当前分组支持的模型重新测试。

第一次接入时，建议先关闭 IP 限制和有效期，等跑通后再逐项开启。

429：请求太多或并发过高 ​

429 通常表示请求频率、并发或速率限制触发了。

常见原因：

  • 客户端同时开了太多请求。
  • API Key 设置了速率限制。
  • 当前分组或上游模型并发有限。
  • 自动化脚本在短时间内重复请求。

处理方式：

  1. 降低客户端并发。
  2. 暂停几十秒后再试。
  3. 检查 API Key 是否配置了速率限制。
  4. 先用一条简单消息测试，确认单次请求能成功。
  5. 如果经常触发，联系管理员确认当前分组限制。

模型不存在或模型不可用 ​

模型错误通常不是 Key 的问题，而是 model 字段和当前分组不匹配。

常见原因：

  • 模型名拼错。
  • 客户端默认模型不是 kapibalaAPI 当前支持的模型。
  • 当前 API Key 绑定的分组不支持这个模型。
  • 客户端显示名称和实际请求模型不是同一个字段。

处理方式：

  1. 打开价格页面或模型列表。
  2. 复制当前可用模型名。
  3. 把客户端里的实际请求模型改成完全一致的名字。
  4. 保存配置并重启客户端。
  5. 重新发送一条简单测试消息。

不要凭感觉把模型名改成“差不多”的名字。模型名通常需要精确匹配。

客户端仍然走旧地址 ​

有时候你已经改了请求地址，但客户端还是在走旧配置。

常见表现：

  • kapibalaAPI 使用记录里没有新增请求。
  • 客户端报的是官方接口错误。
  • 改配置后没有任何变化。
  • 同一台电脑上有多个 provider 或多个配置文件。

处理方式：

  1. 完全退出客户端。
  2. 关闭所有相关终端窗口。
  3. 检查是否有多个配置文件。
  4. 检查环境变量是否只在当前终端生效。
  5. 确认客户端启用的是刚刚配置的 provider。
  6. 重新打开终端和客户端。

Windows PowerShell 里设置的 $env:... 只对当前窗口有效。关掉窗口后就失效。如果想长期生效，建议写入客户端配置文件或系统环境变量。

终端能通，客户端不通 ​

如果你用 cURL 或 PowerShell 可以请求成功，但客户端不通，说明 kapibalaAPI、API Key、余额和分组大概率正常，问题更可能在客户端配置。

重点检查：

  • 客户端 Base URL 是否需要带 /v1。
  • 客户端是否支持你选择的接口类型。
  • 客户端模型名是否写死。
  • 客户端是否需要单独启用 provider。
  • 客户端是否被 CC Switch、EchoBird 或其它配置管理工具覆盖。

建议先回到“配置客户端”页面，按对应工具重新核对一遍。

使用记录里没有请求 ​

如果客户端报错，但使用记录里完全没有新增请求，说明请求可能没有到达 kapibalaAPI。

优先排查：

  1. Base URL 是否还填着官方地址或其它站点地址。
  2. 请求地址是否缺少或多填了 /v1。
  3. 网络代理、防火墙或插件是否拦截请求。
  4. 客户端是否没有读取新配置。
  5. API Key 是否填到了错误 provider。
  6. 请求是否发到了另一个域名。

如果使用记录里有失败请求，说明请求已经到达 kapibalaAPI，再按状态码、错误信息、模型名和分组继续排查。

提供给管理员的信息 ​

如果需要管理员协助，不要只说“不能用”。请尽量提供：

  1. 大概发生时间。
  2. API Key 名称，不要发完整密钥。
  3. 使用的客户端。
  4. 请求地址。
  5. 模型名。
  6. 错误截图或错误文本。
  7. 使用记录里的请求 ID 或失败记录。

不要把完整 API Key、账号凭证、OAuth JSON、私有配置文件发到公开聊天里。

成功标准 ​

完成这一页后，你应该知道：

  1. 先判断问题发生在客户端、请求地址、API Key、分组权限还是模型。
  2. 401、403、429 分别优先检查什么。
  3. 使用记录为空和使用记录有失败请求代表不同方向。
  4. 找管理员协助时应该提供错误信息和请求 ID，而不是完整 API Key。