Template JSON reference

A template's pages_data is an array of pages. Each page has a canvas, layers (elements) and, for video, audio tracks and subtitles. A film also has a template-level film object, sent next to pages_data; see Film. This page lists the fields, then the rules the renderer follows. For how the pieces fit together, start with Template anatomy.

Field reference#

Page#

Canvas#

Element#

Element style#

Transitions#

Enter transition#

Exit transition#

Ambient transition#

Video layer options#

Audio track#

Narration (tts)#

Sound effect (sfx)#

Subtitle#

Page transition (transitionIn)#

Film (template level)#

Elements#

Note. Each element: { id, type, position: { x, y }, dimensions: { width, height }, style: { ... }, zIndex, content }. position and dimensions are nested objects. Send style lengths as px strings ("48px"), fontWeight and minFontSize as unitless strings ("700", "8"), and lineHeight as a number multiplier (1.2).

Types

• text
• image
• shape (shapeType: rectangle|circle|arrow|line)
• element (inline SVG, isSvg:true)
• video
• waveform (visualizes a page audio track)

Parameterizable. Set parameterizable: true, a parameterId and a parameterType (text, imageUrl, videoUrl, backgroundColor, fill, color or stroke). A parameterId uses letters, digits and underscores, such as "headline"; it cannot contain spaces, @, . or :. Layers of the same type on a page may share a parameterId, so one value fills them all; a clash with a layer of another type is renamed with _1, _2. On a multi-page template the render key gets the page prefix, such as page2@headline. The prefix goes on the render key only, never in parameterId.

Opacity. Layer opacity is style.opacity, from 0 to 1.

Flat fields. Create and update also accept flat x, y, width and height on a layer (saved as position and dimensions) and src or src_url (saved as content).

Text#

Line breaks. In plain text use \n for line breaks; <br> also works. Inside rich text (content with tags such as <span> or <b>) \n is not converted, so use <br> there. Use a single <p> or none: several <p> blocks overlap.

Fit. style.textMode: "fit" with style.minFontSize (such as "8") shrinks the text to fit its box when a render sends longer copy.

Align. style.verticalAlign places text in its box: "flex-start" (top), "center" or "flex-end" (bottom).

Shapes#

Outline. A rectangle or circle paints its fill, which defaults to black (#000000). For an outline, set fill to "transparent" and set stroke and strokeWidth. Lines and arrows are drawn with color and strokeWidth.

SVG layers#

Content. type: "element" with isSvg: true. content is an inline data:image/svg+xml URI or the https URL of an .svg file. Percent-encode an inline SVG (encodeURIComponent): a raw # or < cuts the URI short and the layer renders blank. style.svgColor tints a single-colour SVG.

Parts. To animate parts of a drawing, give each moving part an id and target it with motion.svg (see Motion). Keep static placement on an outer <g> and put the id on the inner one.

Waveforms#

Structure. type:"waveform", waveTrack:0 (zero-based page audioTracks index), with normal position/dimensions/zIndex. It needs no content.

Style. style:{ fill, barCount:4-160, barGap:0-24, borderRadius, waveAlign:'center'|'bottom', minBarHeight:0-60 }. The image preview draws a deterministic static waveform; video renders animate it from the selected track.

Dynamic. A parameterized waveform can expose its flat style keys through normal dot modifications such as 'wave1.fill' or 'wave1.barCount'.

Animation#

When. Transitions play in video (mp4, webm) and GIF renders. Static renders show every layer in its final state.

Example

{
  "transitions": {
    "enter": {
      "type": "slideInUp",
      "easing": "ease-out",
      "duration": 0.6
    },
    "showAt": 1.2,
    "ambient": {
      "type": "kenBurns",
      "customValues": {
        "zoom": 1.12,
        "panX": 8
      }
    },
    "exit": {
      "type": "fadeOut",
      "duration": 0.3
    },
    "hideAt": 3.6
  }
}

Visibility windows. showAt and hideAt give each layer a visibility window, in seconds. The exit animation starts at hideAt, so the layer is gone at hideAt + exit.duration. Leave hideAt out (or null) to keep the layer to the end. For a slideshow, stack full-canvas photos and give photo K showAt = cut K and hideAt = cut K+1.

Enter types

• fadeIn
• slideInUp
• slideInDown
• slideInLeft
• slideInRight
• scaleIn
• scaleInUp
• scaleInDown
• rotateIn
• flipInX (3D)
• flipInY (3D)
• textReveal (text only, staggered per word/char)
• typewriter (text only)
• none

Exit types

• fadeOut
• slideOutUp
• slideOutDown
• slideOutLeft
• slideOutRight
• scaleOut
• scaleOutUp
• scaleOutDown
• rotateOut
• flipOutX
• flipOutY
• textRevealOut
• none

Easings

• ease-out (the enter default)
• ease-in (the exit default)
• linear, ease, ease-in-out
• cubic-bezier(0.175, 0.885, 0.32, 1.275) (a bounce)
• spring(stiffness, damping, velocity), such as spring(180, 12, 0): stiffness 20-400, damping 2-40

Custom values. Per-phase intensity via enter/exit.customValues: opacity (start 0-1), offset (slide % ±500, sign = direction), scale (0-5; scaleIn default 0: use { scale: 1.15 } for a subtle zoom-punch to 1.0), angle (deg; rotateIn -180, flips ±90), granularity ('word'|'char': textReveal/typewriter), overlap (10-90 stagger % for textReveal). reverse: true flips a phase's direction.

Ambient. A third phase beside enter and exit: transitions.ambient = { type, duration, easing, customValues } plays for the layer's whole visible life, starting when its enter finishes. kenBurns runs once across the visible window and ignores duration (customValues: zoom 0.5-2, default 1.12; panX and panY ±30%). The loop types repeat every duration seconds (default 4): pulse (amount 1-1.5), float (offset px), drift (offset px), wiggle (angle deg), shake (offset px), slowRotate, and breathe (opacity and scale). shake and slowRotate loop without a visible seam only with easing "linear".

More motion. Transitions have no mid-life motion beyond the ambient types. For more, use element motion (see Motion), which also takes explicit keyframes.

Motion#

Overview. Per-element animation for video pages, beyond transitions. Any element.motion or page.motion switches the page to the motion timeline; transitions on other layers keep working in the same timeline. Static renders ignore motion. All keys are optional unless marked required; out-of-range values are clamped.

Element

Page

Validation. Create and update reject structural problems with a 400 that lists each one: a missing or cyclic after reference, a non-numeric count.to, keyframes that are not an array, more than 200 animated layers or 2,000 tweens on a page, or a page over 120 s. Unknown keys never fail: they are ignored at render and listed in the response warnings with a suggested spelling. Renders never fail on motion; at worst the page falls back to its transitions.

Limits. reveal and typewriter work on text layers only, and typewriter needs plain text. Caps: 200 animated layers per page, 400 reveal words, 512 KB of SVG.

Page audio#

Overview. Video templates carry their own soundtrack: each page has audioTracks (an array) mixed into every mp4 and webm render. A track's source is an existing url, generated narration (tts) or a generated sound (sfx). audioTracks is a page field, next to elements and canvas, not a layer. A render is refused when a page has more tracks than the plan allows per page.

Track fields

Example

{
  "audioTracks": [
    {
      "label": "Narration",
      "tts": {
        "text": "Meet the campaign built for you.",
        "voiceId": "<catalog voice id>",
        "modelId": "flash",
        "parameterId": "voiceover"
      },
      "volume": 1
    },
    {
      "label": "Ambient",
      "sfx": {
        "prompt": "warm modern technology pulse, instrumental, no vocals, seamless loop",
        "seconds": 12
      },
      "volume": 0.12,
      "loop": true,
      "fadeIn": 0.5,
      "fadeOut": 1
    }
  ]
}

Dynamic narration. tts.parameterId makes the spoken text a render parameter. Single page: modifications: { "voiceover": "New script" }; multi-page: { "page1@voiceover": "..." }. The render synthesizes, caches and bills the new script.

Render swap. videoOptions.audioSource replaces an existing URL track at render time while keeping saved trim/fade/volume/offset/loop. It is for soundtrack-file swaps; generated narration uses tts.parameterId instead. There is no generic audio parameterType.

Mixing. Page tracks auto-mix with unmuted video-element audio. videoOptions.muted: true strips all audio from a render.

Subtitles#

Saved. page.subtitle (a page field): { source: "auto-audio" | "upload", url, enabled, mode: "phrase" | "word-by-word", maxWordsPerLine or maxCharsPerLine, wordReveal: "appear" | "highlight" | "align", split: "word" | "letter", fontSize, fontFamily, fontWeight, color, background, position: "top" | "center" | "bottom", offset, paddingX, paddingY, borderRadius, shadowX, shadowY, shadowBlur, shadowColor, wordSpacing }. maxCharsPerLine overrides the word budget; align re-centres the line as spoken words appear. source "auto-audio" captions the page's first enabled audio track that is not a sound effect.

Render time. videoOptions.subtitleSource on a render (a media URL is transcribed automatically; an .srt or .vtt file is used as it is; the array form targets pages and takes trimStart and offset) and the subtitle* keys override the saved config: subtitleWordReveal appear | highlight | align, subtitleSplit word | letter, subtitleMaxWordsPerLine or subtitleMaxCharsPerLine. For captions that follow the audio, save the audio in audioTracks and set the subtitle source to "auto-audio". Do not use the output trimStart and trimEnd to align captions: the caption and video clocks drift apart.

Video layers#

Options. element.videoOptions: { loop, muted (default true; set false to keep the clip's sound), trim_start_time, trim_end_time (snake_case; seconds or "MM:SS"), duration (the clip's own length in s) }. The saved trim applies only when both trim_start_time and trim_end_time are set, and only to the template's own clip; when a render swaps the clip URL, trim it with the render-time keys below.

Render time. Per render: 'clipParam.trimStart': 4.5, 'clipParam.trimEnd': 12, 'clipParam.muted': false, 'clipParam.loop': true (camelCase at the modification layer).

Video render options#

Options. videoOptions on a render request: duration, fps (up to 30), trimStart and trimEnd (together), quality, muted, audioSource, subtitleSource with the subtitle* styling keys, subtitleMode, subtitleWordReveal: appear | highlight | align, subtitleSplit: word | letter, subtitleMaxWordsPerLine or subtitleMaxCharsPerLine, combinePages, pageTransition with its duration, and captionPreset: pill | minimal | karaoke | bold | outline | neon.

Multi page. Multi-scene videos are films: one video whose pages are scenes joined by each page's transitionIn, with music and layers that stay across cuts on film tracks. See Film. combinePages: true still joins the pages of a plain multi-page template, and a string audioSource lays one soundtrack across it.

Canvas sizes#

Note. Suggested canvas sizes in pixels. A canvas side can be up to 5,000 px.

Common

Common mistakes#

• Putting showAt or hideAt inside enter or exit. They are siblings of enter and exit on transitions; inside them the renderer ignores the timing and every layer shows at once. The property is transitions, not animation.
• Mixing unit forms: lengths are px strings ("48px") and lineHeight is a number (1.2).
• Reusing a parameterId on layers of different types on one page (the later one is renamed with _1).
• Several <p> blocks in one text layer (they overlap), or \n inside rich text (it is not converted; use <br>).
• An inline SVG data URI with a raw # or < (it is cut short and renders blank; percent-encode it).
• A shape with backgroundColor and no fill: shapes paint fill, which defaults to black.
• A generic audio parameterType. Swap a soundtrack URL with videoOptions.audioSource; change spoken copy through the track's tts.parameterId.
• videoOptions.trimStart without trimEnd on a render (it needs both).
• Expecting a video layer's own audio to play: its videoOptions.muted defaults to true; set it to false.