正确处理任务状态与错误
稳定的视频接入需要区分处理中状态、最终状态、幂等冲突和临时服务错误。不要根据进度 100 判断成功。
任务状态
| 状态 | 是否终态 | 处理方式 |
|---|---|---|
| queued | 否 | 继续轮询 |
| in_progress | 否 | 继续轮询 |
| completed | 是 | 停止轮询并使用 metadata.url |
| failed | 是 | 停止轮询并记录错误 |
幂等创建
- 同一用户、相同 Key 和相同请求体重复提交时，返回或恢复同一任务。
- 相同 Key 搭配不同请求体返回 409。
- 创建超时、连接中断或返回 5xx 时，不要立即更换 Key 重新提交。
- 保留原 Key 并查询任务或联系平台支持确认，避免重复任务和重复扣费。
- 收到明确的 400、401、403 或 429 后，修正问题可继续使用同一 Key 重试。
HTTP 错误响应
| HTTP | 含义 | 建议 |
|---|---|---|
| 400 | 请求字段、模型或参数不合法 | 按 message 修正请求 |
| 401 | API Key 缺失、无效、停用或过期 | 更换有效 API Key |
| 402 | 余额或额度不足 | 充值或调整额度后重新提交 |
| 403 | 模型、账号、分组或访问来源受限 | 检查权限、模型限制和 IP 限制 |
| 404 | 任务不存在 | 确认任务 ID |
| 409 | 幂等冲突 | 核对原请求体和幂等键 |
| 429 | 提交过快、并发已满或请求限流 | 读取 Retry-After 后等待重试 |
| 5xx | 服务端暂时异常 | 按幂等要求处理并重试 |
{
"code": "invalid_request",
"message": "prompt is required",
"data": null
}日志安全
日志只记录 HTTP 状态、响应体、请求时间、公开任务 ID 和请求 ID。不要记录完整 API Key、Authorization 请求头或包含凭据的媒体 URL。