排查问题

找到对应的现象，照着修。如果这里都没解决，请带上 request_id 联系客服。

第一次调用就失败

401「Missing credentials」。 Authorization 头没有送到。检查运行请求的那个 shell 或进程里是否设置了环境变量（echo ${POPNOW_API_KEY:0:10} 应输出 sk-popnow-），以及代理或 HTTP 库有没有把这个头丢掉。

401「Key format is not recognized」。 这个值不是 PopNow 的密钥——常常是剪贴板里别的东西。密钥以 sk-popnow- 开头。

401「Credentials are invalid or expired」。 密钥已被吊销、过期或输错了。在 API 控制台新建一个。

40310。 账户邮箱还没验证。打开注册邮件里的链接，密钥会立刻可用。

40201「Insufficient balance」。 账户里的积分不够冻结这个任务的金额。视频的冻结额可能比较大；先用 jobs/quote 看价格，再去购买积分。

请求被拒绝

400 并点名某个字段。 input 不符合模型的 schema：字段名拼错、取值不在允许范围内，或缺了必填字段。从模型进入这个模型的参考页对照一下。

400「Invalid callback URL」。 callBackUrl 必须是公开的 HTTPS 地址，端口 443，不带用户名或密码。localhost 和内网地址都会被拒绝。

40004。 模型正常，但现在不支持这组设置。改掉 msg 里点名的设置（通常是分辨率、时长或画面比例）。

50301。 模型暂时接不了任务。稍后再试或换个模型。

413。 JSON 请求体超过了 2 MiB，通常是因为内嵌了图片。改成上传。

任务失败

invalid_asset。 参考文件下载不了或读不出来。在浏览器隐身窗口里打开这个链接：它必须直接下载文件本身，而且不用登录。网盘的分享页不行。

content_rejected。 模型拒绝了提示词或参考图。换个说法、换参考素材，或者换个模型。

timeout 或 expired。 任务用的时间超过了上限。试试更短的时长或更低的分辨率。

generation_failed。 模型跑了但没有产出。同样的输入往往还会失败；改一改提示词或设置。

失败和过期的任务都不花积分。

结果

下载链接返回 403 或「expired」。 签名链接大约 20 分钟有效。用 recordInfo 重新读一次任务，拿新链接。

带上 API 密钥后下载链接反而失败。 不要给签名链接带 Authorization；链接本身就是授权。

我创建的任务 recordInfo 却返回 404。 任务只对创建它的那个密钥可见。用同一个密钥，或去 API 控制台里查。

Webhook

什么都没收到。 确认这个地址能从公网通过 HTTPS 访问、防火墙放行了，并且处理程序会在 15 秒内返回 2xx。投递失败的记录在 API 控制台里能看到。

签名一直对不上。 对原始请求体字节做哈希，而不是重新序列化后的 JSON；用的是 data.taskId、X-Webhook-Timestamp 请求头，以及你最近一次生成的密钥。

同一个任务收到两次。 重试后这是正常的。按 request_id 忽略重复。

上传

PUT 被存储返回 403。 有请求头和票据里的不一致。请原样发送 Content-Type 和 Content-Length，并且不要带 Authorization 头。

提交返回 40003。 上传的文件和你声明的不一致。用正确的 contentType 和 bytes 重新申请票据。

提交返回 409。 票据已过期（大约 20 分钟）。请在上传前一刻再申请。