Caicaini
免费开始

快速入门

身份验证

对 /v1/* 的每次请求都通过 bearer token 进行身份验证。没有 IP 白名单、没有签名请求、没有 nonce——只需在 Authorization 请求头中带上 Caicaini API 密钥即可。

密钥格式

Caicaini API 密钥以 cai_api_ 前缀开头，后面是来自 URL 安全字母表的 32 个随机字符。完整密钥仅在创建时显示一次，之后无法再次获取。我们仅在服务端以明文保存前 12 个字符（前缀加少量随机字节），用于在你的控制台和我们的日志里展示，不会暴露真正的秘密。

其余部分使用 argon2id 哈希存储，并在每次请求时进行恒定时间校验。在热路径上有一个 5 分钟的 Redis 缓存，把校验开销降到接近零。

Authorization 请求头

把密钥作为 bearer token 传入。请求头名称大小写不敏感，但方案大小写敏感——必须写成 Bearer，加一个空格，再加密钥。

请求头
Authorization: Bearer cai_api_YOUR_KEY

验证你的密钥

确认密钥配置无误最便宜的方法是调用 GET /v1/account。它会返回当前的速率限制档位、可用积分余额，以及本月已消费的积分。这个端点不会调用模型，也不会消耗积分。

curl https://caicaini.com/v1/account \
  -H "Authorization: Bearer cai_api_YOUR_KEY"

认证失败时会得到什么

认证失败会返回 HTTP 401，响应体形如下方所示。如果缺少 Authorization 请求头，除标准错误信封外没有额外内容。

响应 · 401
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key."
  }
}

完整的失败类型及成因列表见 错误。

如何安全保存密钥

  • 把密钥放进环境变量（CAICAINI_API_KEY）、密钥管理服务或封装好的部署配置里。绝不要提交到代码仓库，也不要打包进前端。
  • 密钥代表的是你的账户。在你撤销之前，任何拿到密钥的人都能花掉你的 apiCredits。
  • 对于浏览器应用，请通过你自己的服务器代理。浏览器永远不应直接看到密钥。
  • 每个环境（开发、预发、生产）使用独立密钥，每个服务也用独立密钥。这样某个密钥泄漏被撤销时，只会影响泄漏的那一处。

轮换与撤销

前往 /developers/keys 创建、查看和撤销密钥。撤销立即生效；同一事务里 5 分钟的 Redis 缓存也会失效，因此被撤销的密钥几秒内就无法再发起调用。

建议先创建新密钥并完成部署，再撤销旧密钥。每个账户最多 25 把活跃密钥——如果触顶，请先清理不再使用的条目。

权限范围

每把密钥都附带一组权限范围。新开发者密钥的默认范围是 messages.create、models.read 和 usage.read——足以覆盖本参考文档所记录的全部内容。在按密钥粒度执行更细范围（只读密钥、只允许批处理的密钥）落地之前，我们会先把它们加上。在那之前，请把密钥视为对 API 接口拥有完整访问权。

下一篇模型