Skip to main content
角色和动作是可复用的异步素材;渲染任务是生成输出文件的异步操作。

状态生命周期

cancelled 用于渲染状态,客户端无法主动触发,因为没有公开取消操作;任务仍可能自行进入该状态,应视为终态。资源为 queuedprocessing 时每 3–5 秒轮询,进入 readyfailedcancelled 后停止。

轮询示例

渲染与角色、动作的轮询模式一致,只需更换资源 URL。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 流程使用 analyzingrenderingfinishing;草稿流程使用 queuedpreparinggeneratingfinalizing。未知值应按“处理中”处理,不要直接报错。通过 GET /v1/videos/{video_id} 查询时,仅 Render 来源且 status=processing 才有值;H3(vid_)始终为 null
  • video_url:仅渲染就绪后可用。
  • alpha_url:透明输出时可用。
  • linksPOST /v1/renders 响应中的 {self, events, download}。旧版迁移代理处理的任务不包含;GET /v1/videos/{video_id} 响应也完全不包含。

及时下载

video_urlalpha_urlvsplat_urlthumbnail_urlglb_url 都是短期签名链接,每次读取对应接口都会重新签名。后续仍需使用的输出请保存到自己的存储;链接过期时重新请求导出或下载接口,不要长期缓存 URL。

安全恢复

  • 遇到 failed,检查 error.codeerror.retryableerror.remediation,按照建议恢复,见错误与恢复
  • POST /v1/renders 的 JSON 草稿模式要求 Idempotency-Key,网络超时后可用相同键和请求体安全重试。multipart 渲染及角色、动作创建不使用该请求头。已收到创建响应时应查询资源 ID;未收到时,先根据请求日志和 X-Request-Id 确定结果,再决定是否重提。支持 task_id 的 3D 创建模式请遵循各自接口的幂等约定。
  • 联系支持团队时附上 X-Request-Id