401：认证失败

可能原因：

• X-API-Key 写错或复制多了空格。
• Key 被管理员禁用，或者你自己在账户页禁用了。
• Key 已经吊销。
• 全局 API Key 认证被关闭（API_KEY_AUTH_ENABLED=false）。

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

429：请求太频繁

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

400：参数错误

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

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

409：冲突

常见于重复发布：一个任务只能发布一次作品。已经发布过的任务再 POST /api/v1/works 会返回 409。

503：服务未配置

常见于：

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

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

任务 failed

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

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

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