API 文档

除健康检查外，开放 API 接口都需要 API Key。

推荐的请求头

优先使用 Bearer 鉴权：

Authorization: Bearer pcc_live_xxxxxxxxxxxxxxxxxxxxxxxx

也可以使用：

X-API-Key: pcc_live_xxxxxxxxxxxxxxxxxxxxxxxx

两种请求头任选一种，不要同时发送两枚不同的密钥。

创建和撤销密钥

API Key 在“个人中心 → API Key”中管理。

• 每个账号最多保留 10 枚未撤销的密钥。
• 完整密钥只在创建成功时显示一次。
• 撤销后立即失效，不能恢复。
• 可以按项目、环境或服务器分别创建密钥，便于单独撤销。

建议使用能说明用途的名称，例如 production-backend、staging-worker，不要使用 key1、test 这类难以追踪的名称。

服务端保存示例

Node.js：

const apiKey = process.env.PICCC_API_KEY

if (!apiKey) {
  throw new Error('PICCC_API_KEY is missing')
}

const response = await fetch('https://api.picccai.cn/v1/user', {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
})

if (!response.ok) {
  throw new Error(`Piccc API request failed: ${response.status}`)
}

console.log(await response.json())

不要在浏览器中直连

网页或移动端代码里的密钥可以被用户提取。正确做法是：

1. 浏览器请求你自己的后端。
2. 你的后端读取环境变量中的 API Key。
3. 后端调用 Piccc AI，再把需要的结果返回给浏览器。

如果密钥已经出现在仓库、日志或前端包中，立即在个人中心撤销，并创建新密钥。

常见鉴权错误

HTTP 状态码	错误码	处理方法
401	missing_api_key	检查请求头是否发送，以及 Bearer 后是否有空格。
401	invalid_api_key	密钥不存在、已撤销、已禁用或已过期，重新创建后再试。
403	account_unavailable	当前账号不可用，请检查账号状态。