任务生命周期

任务状态

`status`	含义	客户端行为
`queued`	已接受，等待执行	继续查询
`in_progress`	正在生成或处理结果	继续查询
`completed`	成功终态	停止查询，读取并下载结果
`failed`	失败终态	停止查询，展示 `error.message`
`unknown`	状态暂未确定	保留任务 ID，稍后查询，不重提任务

progress 只是显示进度，不保证持续增加，也不能作为判断终态的依据。HTTP 200 的查询响应也可能携带 status: "failed"。

任务 ID 与恢复

提交成功后立即持久化 id（视频兼容响应也可能有 task_id）、媒体类型、模型与提交时间。后续刷新页面、重开应用，继续 GET 该任务即可，不要重新 POST。

客户端超时不代表服务端取消。用户主动关闭页面也不代表任务停止。当前这套公共接口没有在本文中提供取消接口或 webhook，请按查询模式接入。

轮询策略

默认每 5 秒 查询一次，不要每个渲染周期都发请求。
一次查询结束后再安排下一次，避免慢请求叠加。
多任务为每个任务保存独立状态；不要让多个组件重复查询同一个 ID。
429 尊重 Retry-After；网络错误、502/504 可有限退避重试 GET。
401/403 暂停并处理权限；404 不等于任务成功，也不要据此重新生成。
达到客户端等待上限时保留 ID，提示稍后继续查询，不要自行断言任务失败。

这里的 GET 重试与重新生成是两件事。失败终态只会通过一次新的 POST 创建新任务，新的任务可能再次计费。

视频成功响应

{
  "id": "task_example",
  "object": "video",
  "model": "wan3.0-video-ep",
  "status": "completed",
  "progress": 100,
  "created_at": 1788627335,
  "completed_at": 1788627455,
  "metadata": {"url": "https://example.com/result.mp4"}
}

优先遍历 outputs[].url 获取所有视频（例如 MJ 批量结果）；metadata.url 兼容提供第一条，旧任务可能只包含此字段。保留原始响应以便排查兼容性，但不要要求所有可选字段总是出现。

图片成功响应

{
  "id": "task_example",
  "object": "image.generation.task",
  "model": "gpt-image-2",
  "operation": "edit",
  "status": "completed",
  "progress": 100,
  "created_at": 1788627335,
  "outputs": [
    {"object": "image.generation.output", "url": "https://example.com/result.png", "mime_type": "image/png"}
  ]
}

读取所有 outputs[].url。Seedream、GPT Image 2 和 Nano Banana 的 operation 为 generate 或 edit，由参考图片输入决定。MJ 使用显式操作，可能是 variation、upscale_subtle 等；其 describe 成功结果是 descriptions[]，可以没有图片输出。后续操作按返回的 actions 选择，见 Midjourney。

失败响应

{
  "id": "task_example",
  "object": "video",
  "model": "wan3.0-video-ep",
  "status": "failed",
  "progress": 100,
  "created_at": 1788627335,
  "error": {"code": "generation_failed", "message": "The generation request was rejected."}
}

错误文案不是稳定枚举，不要按完整文案写死匹配；保留 code、message、任务 ID 与请求时间。

下载与重复提交

结果地址可能是有时效的签名 URL，不承诺永久有效。成功后及时下载；需要长期保存的应用应维护自己的存储副本。不要删除 URL 的查询参数，也不要在下载第三方地址时附带本站 API Key。

当前没有承诺生成接口的幂等键。POST 超时、连接断开时，可能任务已经创建；先查看控制台任务记录，不要无条件重发以免重复计费。