Overlays Reference

This page is the human-readable companion to the OpenAPI reference. It documents every overlay type a composition can contain, calls out the units each field uses, and flags the surprises (fields that look optional but aren't, fields the renderer silently ignores).

For the literal schema and copy-pasteable examples, see POST /renders.

Fields every overlay has

These come from BaseOverlay and exist on text, video, image, sound, shape, sticker, caption, and effect alike.

Positioning cheatsheet

top and left are pixels from the top-left corner of the canvas - (0, 0) is the top-left. To pin a 300×300 element to the bottom-right of a 1080×1920 canvas with a 40 px margin:

top  = canvasHeight - height - margin   →  1920 - 300 - 40 = 1580
left = canvasWidth  - width  - margin   →  1080 - 300 - 40 =  740

Row stacking

row is the timeline track index, and it directly drives stacking order: the renderer computes zIndex = 100 - row * 10, so lower row numbers sit on top.

• A text overlay on row: 0 renders above a video overlay on row: 1 - the video becomes the background for the text.
• Background video / full-frame effects belong on the highest row numbers (e.g. row: 4 or row: 5).
• Headlines, CTAs, and anything that should sit in front of everything else belong on row: 0 or row: 1.
• Give each visually-stacked overlay its own row. Two overlays on the same row will collide - they share a z-index, and the order falls back to the array order, which is fragile.

A safe convention for a full composition: row: 5 audio · row: 4 background video/effect · row: 3 scrim/dim shape · row: 2 decorative graphics · row: 1 body text · row: 0 headline.

text

{
  "id": 1, "type": "text",
  "content": "Hello world",
  "from": 0, "durationInFrames": 90,
  "row": 1, "top": 800, "left": 60, "width": 960, "height": 200,
  "styles": {
    "fontSize": "4rem", "fontWeight": "900",
    "color": "#FFFFFF", "textAlign": "center",
    "animation": { "enter": "fade", "exit": "fade", "enterDuration": 0.4 }
  }
}

• content is the rendered string. When isDynamic is true, this is what replacements swaps.
• styles.fontSize accepts any CSS size string ("3rem", "48px").
• styles.animation - preset enter/exit. enterDuration / exitDuration are in seconds.
• styles.animatedText, styles.typeWriter, styles.counterMode, styles.codeBlock - alternate text modes, each with enabled: true to activate. See the editor doc for what each does.

video

{
  "id": 0, "type": "video",
  "src": "https://example.com/clip.mp4",
  "from": 0, "durationInFrames": 180,
  "row": 0, "top": 0, "left": 0, "width": 1080, "height": 1920,
  "videoStartTime": 2,
  "speed": 1,
  "styles": {
    "objectFit": "cover", "opacity": 1
  }
}

• src - public URL of the source media. Replaced by replacements if isDynamic is true.
• videoStartTime - in-point of the source clip in seconds. Skips the first N seconds of the source.
• speed - playback speed multiplier. 2 plays twice as fast; 0.5 plays at half speed.
• mediaSrcDuration - total length of the source media in seconds. Helps the editor compute trim boundaries.
• segments - ordered list of { startFrame, endFrame, speed? } slices to chain together. When set, videoStartTime is ignored. Frames are absolute source frames.
• greenscreen - chroma-key removal. { enabled: true, sensitivity, threshold: { red, green, blue }, smoothing, spill }.
• styles.volume - 0-1. Defaults to the source's natural volume; set to 0 to mute.
• styles.cropEnabled / cropX / cropY / cropWidth / cropHeight - percentages (0-100) of the source frame to display. Set cropEnabled: true to apply.

image

{
  "id": 2, "type": "image",
  "src": "https://example.com/photo.jpg",
  "from": 0, "durationInFrames": 90,
  "row": 1, "top": 200, "left": 100, "width": 400, "height": 400,
  "styles": {
    "objectFit": "cover", "borderRadius": "16px", "opacity": 0.85
  }
}

• styles.opacity - 0-1. Combined with the composition's backgroundColor, this is how you tint or darken an image.
• greenscreen - same shape as video.
• styles.layout3D.layout - tilt the image into 3D. One of none, tilt-up, tilt-down, card-left, card-right, book, floating, billboard, skewed. See 3D layouts below.
• styles.layout3D.settle - true makes the tilt an animation instead of a fixed pose: the image arrives at the full angle and rotates to flat. See 3D layouts.
• styles.animation - enter/exit preset with optional duration in seconds.
• Crop fields are the same as video.

3D layouts

layout3D is the only depth control, and it works on image overlays only. On its own it is a fixed pose - the image holds the same tilt for its whole life:

{ "styles": { "layout3D": { "layout": "card-right" } } }

Add "settle": true and the tilt becomes a move. The image arrives at the preset's full angle and rotates to flat over its entry animation, landing squarely on its top/left/width/height box. This is what you want for a screenshot, product card or device frame that should arrive in 3D rather than sit in 3D:

{
  "id": 4, "type": "image",
  "src": "https://example.com/screenshot.png",
  "from": 0, "durationInFrames": 120,
  "row": 2, "top": 150, "left": 1120, "width": 520, "height": 1040,
  "styles": {
    "borderRadius": "62px",
    "layout3D": { "layout": "card-right", "settle": true },
    "animation": {
      "enter": "slideLeft",
      "enterDuration": 1.15,
      "enterEasing": "easeOutCubic"
    }
  }
}

The rotation is timed by animation.enterDuration (seconds) and shaped by animation.enterEasing, so it runs together with whatever entry animation you pick. easeOutCubic over 1.0-1.4 s reads well; anything under ~0.6 s is over before the eye registers it.

Without settle, the pose is static, so pair it with styles.animation.during (sway or float) to keep it from reading as a still. With settle, keep during subtle - an intensity around 0.12 is enough once the rotation is doing the work.

sound

{
  "id": 3, "type": "sound",
  "src": "https://example.com/music.mp3",
  "from": 0, "durationInFrames": 180,
  "row": 2, "top": 0, "left": 0, "width": 0, "height": 0,
  "startFromSound": 5,
  "speed": 1,
  "mediaSrcDuration": 145,
  "styles": {
    "volume": 0.8, "fadeIn": 1, "fadeOut": 1.5
  }
}

• startFromSound - in-point of the source audio in seconds. Use this to skip an intro.
• speed - playback speed multiplier.
• styles.fadeIn, styles.fadeOut - fade durations in seconds.
• styles.volume - 0-1.

shape

{
  "id": 4, "type": "shape",
  "content": "rectangle",
  "from": 0, "durationInFrames": 90,
  "row": 1, "top": 100, "left": 100, "width": 200, "height": 200,
  "styles": {
    "fill": "#FF0080", "borderRadius": "16px",
    "animation": { "enter": "scale", "exit": "fade" }
  }
}

• content - shape identifier. One of "rectangle", "circle", "triangle", "star", "diamond", "hexagon", "arrow", "line". Unknown values fall back to "rectangle".
• styles.gradient - single CSS gradient string.
• styles.gradientTransition - animated transition between multiple gradient strings.

sticker

{
  "id": 5, "type": "sticker",
  "content": "discount-50",
  "category": "Discounts",
  "from": 30, "durationInFrames": 90,
  "row": 2, "top": 500, "left": 740, "width": 300, "height": 300,
  "styles": { "scale": 1, "animation": { "enter": "bounce" } }
}

• content - sticker identifier from the sticker library.
• category - one of "Shapes", "Discounts", "Emojis", "Reviews", "Default".
• styles.scale - uniform scale multiplier.

caption

{
  "id": 6, "type": "caption",
  "captions": [
    {
      "text": "Hello world",
      "startMs": 0, "endMs": 1200,
      "timestampMs": null, "confidence": 0.97,
      "words": [
        { "word": "Hello", "startMs": 0,   "endMs": 500,  "confidence": 0.98 },
        { "word": "world", "startMs": 600, "endMs": 1200, "confidence": 0.96 }
      ]
    }
  ],
  "from": 0, "durationInFrames": 90,
  "row": 3, "top": 1500, "left": 60, "width": 960, "height": 200,
  "styles": {
    "fontSize": "3rem", "color": "#FFFFFF",
    "textAlign": "center",
    "highlightStyle": { "color": "#FFD700", "scale": 1.1 }
  }
}

• captions[] carries one entry per phrase, each with word-level timing.
• styles.highlightStyle is what the currently-spoken word looks like - karaoke-style emphasis.
• template - an optional named style template (set by the editor).

effect

{
  "id": 7, "type": "effect",
  "content": "confetti",
  "from": 0, "durationInFrames": 180,
  "row": 4, "top": 0, "left": 0, "width": 1080, "height": 1920,
  "styles": { "particleCount": 200, "speed": 1, "size": 8 }
}

• content is the effect preset: one of "snow", "confetti", "rain", "fireflies", "sparkles", "bubbles", "matrix", "grid-stagger", "fracture", "scrolling-columns".
• Each preset takes its own subset of styles. Matrix effects use matrixFontSize / matrixColor / matrixDensity / matrixCharset; grid effects use gridCols / gridRows / cellColors / cellImages / staggerDelay; scrolling columns use columns[] / columnGap / imageHeight.

Composition-level fields

These sit at the top of inputProps, not inside any overlay:

Where to next

• Templates - turn any overlay into a per-render variable
• Rendering - kick off a render job and poll for the result
• API reference - every field with its OpenAPI schema