限流与配额

平台的限制分成几类，触发的表现各不相同。分清楚是哪一类，才能快速处理。

请求频率限制

平台对请求频率有限制。轮询过快、并发过高，或短时间内大量重试，都可能触发：

{ "error": { "code": "...", "message": "请求过于频繁" } }

HTTP 状态为 429。

正确做法：

• 收到 429 后退避：等待一段时间再发下一次请求，不要立刻重发；
• 不要用并发请求绕过限流，这只会让退避时间更长；
• 轮询异步任务时使用固定且合理的间隔（例如几秒一次），不要无间隔轮询。

不要对 429 之外的状态码盲目重试：

异步任务并发

视频等异步任务受并发上限约束，分为单账号维度和平台整体维度。达到上限时返回 HTTP 429， 错误码为 task_concurrency_exceeded，提示中会给出「当前 N 个 / 上限 M 个」。

遇到时应当：

1. 保留已有任务的 ID，不要丢弃；
2. 等待在途任务进入终态（或直接查询它们的当前状态）；
3. 等待后再由用户主动重新提交，不要连续重试；
4. 不要为了"抢"并发而重复提交同一个任务——那会产生重复任务和重复费用。

批量提交前，建议在业务后端做队列化管理：控制在途任务数量，而不是一次性全部提交。

Key 额度与账户余额

额度与余额是两层限制：

异步任务在提交前会校验余额能否覆盖本次预估消耗。不足时会返回可读提示， 并且不会创建任务，因此这种情况不会产生费用。

处理方式：

• Key 额度不足 → 在「API 密钥」里调整该 Key 的额度或有效期；
• 账户余额不足 → 到「钱包」充值或使用套餐；
• 预估消耗过大 → 降低分辨率、时长或改用更小的模型。

建议在业务后端对余额做前置判断，向最终用户给出清晰提示，而不是把平台的错误直接抛给用户。

素材限制

素材接口对上传数据有校验：

素材审核未完成不是错误：查询返回 200 且 status 为 Processing，继续用同一个素材 ID 轮询即可， 不要重复提交。

轮询建议

异步任务的查询不产生费用，但过密的轮询会触发限流。

轮询应有总时长上限。达到上限后停止查询并向用户返回任务 ID，让用户可以稍后凭 ID 继续查询—— 不要重新创建任务。

幂等与重复提交

平台不会自动合并相同的请求。即使提示词、参数和参考素材完全相同，每次主动提交都会创建 新的任务和新的结果，并各自计费。

因此：

• 用业务侧的幂等键（订单号、业务 ID）防止用户重复点击导致重复提交；
• 异步任务提交后立即在数据库中保存任务 ID，网络中断时用查询而不是重新创建来恢复；
• 只有对同一条失败结果点击「直接重试」时，才会在原位置重新执行——这同样会产生新任务和新费用。