鉴权

每个 API 请求都要在 Authorization 请求头里带一个 API 密钥：

Authorization: Bearer sk-popnow-3f9c0a…

没有别的认证方式：密钥放在 URL 查询参数里一律不接受，你在 popnow.ai 网站的登录状态在 API 上也不起作用。

只有一个例外：/v1 下的 OpenAI 兼容接口 也认 x-api-key 请求头里的密钥，OpenAI 风格的客户端不用改。原生 /api/v1 接口只认 Authorization。

密钥长什么样

密钥是 sk-popnow- 加上 48 个小写十六进制字符。创建之后，API 控制台只会显示开头几位，所以丢了的密钥找不回来——再建一个新的就好。

创建密钥

1. 登录 popnow.ai，打开 API 控制台。
2. 点 Create key，起一个能说明用途的名字，比如 production-backend。
3. 马上复制。完整的密钥只显示这一次。

一个账户可以同时有多个密钥。建议每个环境、每个服务各用一个，这样吊销其中一个不影响其他的。所有密钥共用同一个积分余额。

密钥放在哪

• 放进环境变量或平台的密钥管理（POPNOW_API_KEY），不要写进源代码。
• 绝不要放进浏览器、手机 App 或任何跑在别人设备上的代码里。谁能读到密钥，谁就能花你的积分。让你自己的服务器夹在中间，由它去调用 PopNow。
• 不要写进日志。如果你会记录请求头，先去掉 Authorization。

限制密钥能做什么

每个密钥都可以在 API 控制台里单独设置限制：

默认情况下密钥没有任何限制，也没有上限。生产环境的密钥，给到够用的最小范围就好。

任务属于创建它的那个密钥

recordInfo、retry、purge、任务列表和用量，都只能看到同一个密钥创建的任务。用账户里另一个密钥创建的任务会返回 404，和不存在的任务完全一样。你在网站上发起的生成，任何密钥也都看不到。想看整个账户的情况，请用 API 控制台。

轮换

不停机地替换一个密钥：

1. 创建新密钥。
2. 把它部署到所有用到旧密钥的地方。
3. 在控制台里看旧密钥的「最近使用时间」不再变化。
4. 吊销旧密钥。

密钥泄露了

1. 立刻吊销：在 API 控制台操作，下一个请求起生效。
2. 换上新密钥并部署。
3. 查它被用来做了什么：控制台的日志和用量会列出这个密钥创建的每个任务。
4. 给新密钥收紧权限：加上 IP 白名单和消费上限。

如果发现不是你发起的消费，请联系客服。

失败时长什么样

三种鉴权问题都返回 HTTP 401、code: 401，靠 msg 区分：

密钥有效也可能被 403 拒绝，比如账户邮箱还没验证（40310）。见错误码。