错误处理

接口错误遵循 HTTP 状态码，并在响应体中返回可读错误信息。参数错误不会创建上游任务，也不会产生最终生成费用。

常见状态码

状态码	常见原因	建议
400	参数越界、模型不支持分辨率、素材状态错误	根据错误字段修正请求
401	API Key 缺失或无效	检查 Authorization
403	用户、令牌或渠道分组无权访问	检查分组和模型权限
404	任务、素材组或素材不存在	核对平台返回的 ID
409	重复提交、资源状态冲突	保留请求 ID，查询已有任务
429	频率、并发或额度限制	遵循 Retry-After 并退避重试
500/502/503	平台或上游暂时异常	使用同一业务幂等键谨慎重试

官方参数边界

参数	允许范围
duration	4～15 的整数，或 -1
resolution	当前标准模型支持 480p、720p、1080p，并需配置对应价格
ratio	16:9、4:3、1:1、3:4、9:16、21:9、adaptive
seed	-1～4294967295
execution_expires_after	3600～259200 秒
safety_identifier	最长 64 个字符
callback_url	解析到公网地址、使用 80/443 端口的 HTTP/HTTPS URL

素材错误

• asset:// 引用必须属于当前用户和实际调用渠道。
• PROCESSING 素材尚未就绪，应稍后查询；不要直接提交生成。
• FAILED 素材需查看错误后重新上传。
• 素材类型必须与 content.type 一致。
• 新版与旧版素材 ID 不可混用。
• URL 导入不支持 Base64、data: URL、本地路径、内网地址或非 HTTP/HTTPS 协议；Base64 请解码后使用 multipart 上传。

部分上游会把业务参数错误包装为 HTTP 500。客户端应同时读取响应体中的 error.type、error.code 和 error.message，不要只根据 HTTP 状态码判断是否适合重试。明确的参数错误应修改请求，而不是原样重试。

异步任务恢复

• 创建成功后立即持久化任务 ID。
• 对超时请求先查询任务，避免直接重复创建。
• failed、cancelled 或 expired 为终态；记录 error 和请求 ID 后再决定是否重试。
• 回调与轮询都必须幂等，避免重复写入结果。
• 任务失败或取消后，异步预扣额度会按结算规则退回。