视频渲染 API 工作流：从 Schema 到最终 MP4

生产环境的视频 API 不应该是一个长时间阻塞的 HTTP 请求。渲染耗时可能超过普通请求超时，还会消耗计费资源并依赖远程素材，因此可靠的集成必须把它当成有状态的异步工作流。

RenderingVideo 将“创建任务”和“启动渲染”分开。你可以先验证并保存视频定义，再决定什么时候消耗积分执行渲染。

五个阶段

1. 发现能力： 查询当前 Schema 版本以及支持的片段、动画、转场和质量选项。
2. 准备 Schema： 确认素材公开可访问，并验证时序、尺寸与必填字段。
3. 创建任务： 保存视频定义并取得任务 ID。
4. 启动渲染： 设置 worker 数量，并按需传入完成通知地址。
5. 交付结果： 轮询状态或处理 Webhook，把最终文件地址写回自己的业务系统。

先创建，再渲染

API Key 只应保存在可信后端。创建任务时提交完整 Schema，还可以附带 title、category 和 metadata 等业务字段。

POST /api/v1/video
Authorization: Bearer sk-your-api-key
Content-Type: application/json

创建任务不会自动开始渲染，这非常适合需要人工审批、定时批处理或先留存审计记录的场景。

随后用任务 ID 启动渲染：

{
  "num_workers": 5,
  "webhook_url": "https://app.example.com/webhooks/renderingvideo"
}

渲染参数使用 webhook_url 与 num_workers。输出质量由 Schema 的画布尺寸决定，不要自行添加不存在的 quality 参数。

明确记录任务状态

业务数据库至少应保存远端任务 ID、当前状态、输入版本、请求时间、最终地址和最近一次错误。产品界面的状态机保持简单即可：排队中、渲染中、已完成、失败。

需要分别处理 Schema 无效、积分不足、远程素材加载失败以及重复启动等情况。面向运营人员的错误要可执行，面向终端用户的提示则不应泄露无关的基础设施细节。

轮询与 Webhook 配合

轮询容易实现，也适合作为兜底。Webhook 可以减少无效请求并更快收到结果。稳健的做法是同时支持两者：Webhook 到达后，再通过 API 确认最新状态，然后执行发布、扣库存等不可逆操作。

Webhook 接口应快速返回。下载、转码、发布和通知等耗时工作应进入后台队列。

在自己的系统中保证幂等

一个本地作业只对应一个 RenderingVideo 任务 ID。客户端重试时应返回已有作业，而不是重复创建任务。启动渲染前也要检查是否已经存在 render task 或终态。

这样可以保护积分，并让客户历史记录更清晰。

上线检查清单

• API Key 只保存在服务端。
• 创建任务前完成 Schema 验证。
• 适合的流程先预览审批，再开始计费渲染。
• 在响应客户端之前持久化任务 ID。
• 轮询包含退避策略和最长等待时间。
• Webhook 处理快速且可重复执行。
• 按保留策略保存或引用完成文件。
• 错误信息足够支持安全重试。

完整字段请查看 API Reference。使用较新的 Schema 能力前，先调用 GET /api/v1/capabilities。