CLIPUS PROTOCOL

Universal Video JSON

v1.0-draft

UVJ is the render contract behind every Clipus video. When Clipus reads a SaaS product and generates demo videos, each platform × language output is described by one UVJ document: canvas, timeline elements, voiceover, subtitles — and evidence provenance pointing back to the Intelligence Report the video was generated from. The same document drives browser rendering (WebCodecs) and the server fallback renderer.

Draft status. This spec is published for feedback (internal spec version 0.1). Field names and shapes may change without notice. Compatibility guarantees begin with v1.0 final.

Document shape

One UVJ document = one render variant. A campaign holds an array of them (one per platform × language). Unknown fields are preserved by the validator, and the published surface is the variant document itself — campaign-level strategy data is not part of this contract.

FieldTypeDescription
projectIdstringCampaign this variant belongs to.
platformyoutube_shorts | tiktok | instagram_reels | linkedinTarget platform. One variant per platform × language.
langstring?Language key ("original", "ko", "ja", …). Omitted means original.
version1Runtime shape version of the variant document.
sourceobject?Evidence provenance: which Intelligence Report (id, tier, targetUrl) and which report items this video was generated from.
canvas{ width, height, fps, duration, bgColor }Output canvas. Duration in seconds.
elements[]screenshot | text | subtitle | shape | cursor | text_cardTimeline elements with start/end (seconds), positioning, effects, zoom keyframes, and cursor paths.
audio{ voiceover, bgm? }Voiceover URL + duration; optional background music with volume.
subtitles[]{ text, start, end, isHighlight }Sentence-level subtitle track. Word-level timings live on text_card elements.
screenshots[]{ url, order, language? }Source screenshots the elements reference, in display order.

Example

{
  "projectId": "prj_123",
  "platform": "youtube_shorts",
  "lang": "original",
  "version": 1,
  "source": {
    "type": "intelligence_report",
    "id": "rep_456",
    "reportTier": "deep",
    "targetUrl": "https://example-saas.com",
    "selectedReportItemIds": ["move_1"],
    "segmentIntentIds": ["hook_pain"]
  },
  "canvas": { "width": 1080, "height": 1920, "fps": 30, "duration": 24, "bgColor": "#000000" },
  "elements": [
    { "type": "text_card", "content": "Your dashboard, demoed", "start": 0, "end": 2, "textCardStyle": "hook" },
    { "type": "screenshot", "src": "https://cdn.clipus.io/shot-1.png", "start": 2, "end": 6, "effect": "ken-burns" },
    { "type": "cursor", "start": 3, "end": 5, "path": [{ "x": 0.42, "y": 0.31, "time": 3.2, "click": true }] }
  ],
  "audio": { "voiceover": { "url": "https://cdn.clipus.io/vo.mp3", "duration": 23.4 } },
  "subtitles": [{ "text": "This is the part your users never find.", "start": 2.1, "end": 4.0, "isHighlight": false }],
  "screenshots": [{ "url": "https://cdn.clipus.io/shot-1.png", "order": 0 }]
}

Why provenance is in the schema

Clipus generates videos from real product data — the DOM it reads, the report it wrote — not from a text prompt. The source field keeps that chain auditable: every video can point back to the Intelligence Report and the specific report items it was generated from.

Feedback

The draft is published to collect feedback from teams building on the Clipus API and MCP tools. Tell us what breaks for you before v1.0 freezes: