如何设计可维护的视频 JSON Schema

JSON 让应用和 AI Agent 能精确描述视频，但“验证通过”不等于“容易维护”。好的 Schema 会把可复用资源与镜头指令分开，让时间线一眼可读，并限制动态数据的边界。

从三层结构开始

RenderingVideo Schema 包含三个顶层区域：

• meta 定义画布、帧率、背景和描述信息。
• assets 保存可复用的字体、图片、视频、音频、字幕、模型与 SVG。
• tracks 保存真正出现在画面中的定时片段。

{
  "meta": {
    "version": "2.0.0",
    "title": "Weekly report",
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "background": "#0B1020"
  },
  "assets": {
    "images": [{ "id": "logo", "src": "https://cdn.example.com/logo.png" }]
  },
  "tracks": [
    {
      "id": "titles",
      "clips": [
        {
          "type": "image",
          "src": { "$ref": "logo" },
          "start": 0,
          "duration": 5,
          "transform": { "x": 0, "y": -300, "width": 240, "height": 80 }
        }
      ]
    }
  ]
}

素材负责身份，片段负责行为

共享 Logo 或字体放进 assets，它在画面中的位置和时间放进 clip。使用 ID 引用素材，既能避免在文档中反复复制长 URL，也让替换资源更安全。

ID 应稳定且有含义，例如 brand-logo、music-bed、subtitles-main，不要绑定数组序号或临时数据库记录。

让时间线一眼可读

每个片段都应明确设置 start 和 duration。轨道可以按职责划分为背景、媒体、标题、字幕和覆盖层。这样组织不会自动决定叠放关系，但能显著提高审核和排错效率。

生成式内容最好只计算一次场景边界，再传给所有相关片段。不要让大量对象各自累加小数时长，否则很容易出现闪帧或空隙。

限制动态输入

产品名称、价格、颜色、素材 URL 和字幕词属于数据；片段类型、布局规则和动画选择属于模板逻辑。任何动态字符串或数字在合并进 Schema 前都要验证。

常见限制包括最大文案长度、允许的颜色格式、公开 HTTPS 素材地址、正数尺寸与最大视频时长。可选内容缺失时要有明确回退方案。

保持组合小而清楚

一个片段可以同时拥有动画和关键帧，但把所有行为塞进巨大的对象会让修改变得危险。独立视觉意图应拆成不同片段和轨道；标题卡、产品网格和字幕样式等重复结构则适合做成模板。

用真实渲染器验证

Schema 能力会持续演进。认证流程可以查询 GET /api/v1/capabilities，视觉效果则通过公开预览接口确认。类型检查能发现结构错误，真实预览才能发现字体度量、远程素材和时序问题。

把 Schema 和产品一起版本化

保存源 Schema、模板版本以及生成它的业务输入。客户报告问题时，应能重现当时的结果，而不是用今天的模板重新生成一个近似版本。

可维护的视频 Schema 不只是请求载荷，它还是可编辑资产、审计记录，以及业务数据与渲染器之间的稳定接口。

可以继续阅读 JSON 字段说明，或在 Playground 修改可运行示例。