轮询任务并下载可用产物

创建响应不等于动画完成

POST /animations 返回 HTTP 202、任务 ID 和 Retry-After。收到 ID 后优先保存；进入队列不代表生产已经完成。

轮询 GET /animations/{id}。优先遵循服务的 Retry-After（目前通常约五秒），遇到临时错误使用有界退避，并设置总体截止时间。不要因为轮询慢就创建新任务。当前公开流程以轮询为主，不提供 Webhook 工作流。

状态与阶段

stage 在适用时标明 video_generation 或 animation_export。progress 范围为 0 到 1，不是精确剩余时间。两次轮询间任务可能跨过多个状态，不保证你观察到每个中间状态。

credits.quoted、credits.held、credits.charged 分别表示报价、预占和已扣，不要把初始报价当作最终扣费，也不要把三者相加。

失败仍可能有可用产物

一键任务可能先成功生成源视频，再在导出阶段失败。进入终态时，无论 status 是否为 succeeded，都要检查 outputs。

先下载已有资产，再记录错误和缺失的请求格式，准确报告部分完成。只重做必要步骤：已有源视频可以通过 /animation-exports 重新导出，不必重新生成动作。

安全下载

每个资产包含 id、format、mime_type、byte_size、download_url 和 download_expires_at。

1. 用任务 ID 或资产 ID 保存长期应用状态。
2. 使用返回的签名 URL 下载字节。
3. 不要把 API Bearer 头发送给签名 URL 或重定向后的存储主机。
4. 使用应用自己决定的文件名，并确认下载完整。
5. 链接过期时，用 API Key 调用 GET /assets/{asset_id} 获取新链接。

链接有效期较短，应读取 download_expires_at，不要写死时长。资产已受存储或保留策略移除时，重新查询不会恢复文件。

签名 URL 相当于临时凭据，不应发布到日志、分析事件、工单或 AI 对话记录。

取消任务

对归属自己的任务调用 POST /animations/{id}/cancel。取消属于尽力而为，返回的可能仍是中间状态；继续轮询到终态。任务完成也可能先于取消生效。

已经执行的生产可能保留扣费，未消耗的预占可以释放。应检查返回的积分数据，不要承诺一定全额退款。

先审核再导出：两阶段流程

使用 POST /video-generations 创建视频，再轮询 GET /video-generations/{id} 取得视频资产。审核后，把 source_video_asset_id、选段和导出设置提交到 POST /animation-exports，轮询 GET /animation-exports/{id}。

每个新的付费创建操作都应先报价，并使用自己的幂等键。源资产 ID 和任务 ID 不是同一种资源，不能互换。快速开始示例演示的是更简单的一键生命周期。