401：认证失败

可能原因：

• X-API-Key 写错或复制多了空格。
• Key 已被禁用或吊销。

处理：先到账户页确认 Key 状态，再重新生成一把试试。

429：请求太频繁

限流默认每分钟 20 次。看响应头 Retry-After，按秒数等。脚本里要做退避，不要立刻重试。

400：参数错误

响应里的 detail 会写具体原因。常见：

• duration 超过当前分辨率上限。
• resolution 不是 480p 或 768p。
• 上传的媒体格式不支持。
• size_bytes 和实际上传大小不一致。

409：冲突

请求与当前状态冲突。看响应里的 detail 确认具体原因，避免重复提交同一个写操作。

503：服务未配置

常见于：

• 提示词优化/标签生成：DASHSCOPE_API_KEY 没配。
• 参考素材上传：R2 存储没配。

这种情况不是你的参数问题，是平台配置问题。

任务 failed

任务失败时 GET /api/v1/task/{task_id} 的 error 字段会写明原因。常见：

• 显存不够：降低分辨率或时长。
• 节点超时：稍后重试。
• 参考素材读不到：确认媒体已经 active。

如果 error 看不出原因，把 task_id 和 error 一起发给管理员。