状态生命周期
cancelled 用于渲染状态,客户端无法主动触发,因为没有公开取消操作;任务仍可能自行进入该状态,应视为终态。资源为 queued 或 processing 时每 3–5 秒轮询,进入 ready、failed 或 cancelled 后停止。
轮询示例
GET /v1/renders/{render_id} 已停用并返回 405,请改用 GET /v1/videos/{video_id},也支持 H3 的 vid_ ID。见获取视频与列出视频。
使用监听替代轮询
GET /v1/renders/{render_id}/events 通过 SSE 提供同一生命周期:连接时发送快照,状态变化时发送事件,每 10–15 秒发送心跳,进入终态后关闭连接。它可减少轮询延迟与请求量;断开后使用 Last-Event-ID 重连。见监听渲染。角色和动作没有对应事件流,需要轮询。
渲染进度
渲染响应可能包含:progress:可用时为 0–100 的整数。stage:大致阶段。直接 multipart 流程使用analyzing、rendering、finishing;草稿流程使用queued、preparing、generating、finalizing。未知值应按“处理中”处理,不要直接报错。通过GET /v1/videos/{video_id}查询时,仅 Render 来源且status=processing才有值;H3(vid_)始终为null。video_url:仅渲染就绪后可用。alpha_url:透明输出时可用。links:POST /v1/renders响应中的{self, events, download}。旧版迁移代理处理的任务不包含;GET /v1/videos/{video_id}响应也完全不包含。
及时下载
video_url、alpha_url、vsplat_url、thumbnail_url 和 glb_url 都是短期签名链接,每次读取对应接口都会重新签名。后续仍需使用的输出请保存到自己的存储;链接过期时重新请求导出或下载接口,不要长期缓存 URL。
安全恢复
- 遇到
failed,检查error.code、error.retryable和error.remediation,按照建议恢复,见错误与恢复。 POST /v1/renders的 JSON 草稿模式要求Idempotency-Key,网络超时后可用相同键和请求体安全重试。multipart 渲染及角色、动作创建不使用该请求头。已收到创建响应时应查询资源 ID;未收到时,先根据请求日志和X-Request-Id确定结果,再决定是否重提。支持task_id的 3D 创建模式请遵循各自接口的幂等约定。- 联系支持团队时附上
X-Request-Id。

