Author a video

​

The model

​

Semantics you must know (renderer behavior)

• Times are absolute output-timeline seconds. time = when the element appears; text/image/shape need duration. Video/audio length comes from in_point/out_point (seconds into the source file); always set out_point explicitly.
• Layering: the painter’s rule. An explicit z_index always wins between distinct values; among elements that don’t set one (defaults: text 1, everything else 0), ties resolve by array order — later in elements renders on top. So an overlay listed after a video stacks above it with no z_index needed; set z_index only to override array order.
• Positions/sizes: x/y are the element’s CENTER as canvas percentages ("50%" = centered). width/height accept "38%" (of canvas) or "140px". Font sizes are pixels at the canvas width — the renderer normalizes font_size by width only, so the same value is the same visual size whatever the output height. Rescaling a measurement from a reference frame uses the width ratio, never the height ratio.
• Entrances/exits: "reversed": true runs a preset’s exit form, and only presets that ship both accept it (fade, slide_*, wipe_*, rotate_*, bounce). Entrance-only presets have a separate exit-only twin instead — zoom_out (not zoom_in reversed), evaporate (not blur), whip_down, drift_out, swing_out, elastic_drop — and those six set reversed for you, so never type it. Asking for a missing exit form is a 422 that names the replacement. Motion time is absolute; for entrances and loops set it to the element’s time, for exits to element time + duration − motion duration. delay only shifts that start (time + delay) on a non-loop motion, and spaces the repeats on a loop_* one — it never staggers glyphs. Per-glyph or per-word stagger is spacing on the motion entry: 1 (the engine default) plays the glyph windows fully sequentially, smaller values overlap them, and block animations ignore it.
• Motion presets are surface-split. Text elements and everything else load animations from two different renderer directories that overlap on only a handful of names, so a preset is not portable: blur and evaporate are text-only; swing_in, tilt_zoom, ken_burns_* and identity are element-only; fade, slide_* and zoom_* work on both. A mismatch is a 422 naming the other surface. scope: "character" applies only to per-glyph text presets — whole-block presets (fade, slide_up, zoom_in) reject it. Read GET /v1/capabilities → motions[], where each preset carries element_entrance / element_exit / character / text_block, before picking one.
• Gradient angle_degrees is mathematical (counterclockwise, y-up): 0° runs left→right (offset 0 at the left), 45° bottom-left→top-right, 315° top-left→bottom-right. The same convention governs a shape’s gradient fill and the request-level background_gradient. A CSS string is converted for you (angle_degrees = (90 − css_deg) mod 360), and a numeric CSS angle is box-relative: 135deg behaves as to bottom right whatever the card’s aspect, so only 0/90/180/270 are pixel-exact on a non-square box. A radial center.y runs bottom-up — {x: 0.5, y: 0} is the bottom edge, the opposite of CSS at 50% 100%.
• Per-word captions: word_animation.words[*].start/end are ABSOLUTE timeline seconds (not element-relative). Styles color and box paint with the element’s background_color, which is required for them — omit it and the request 422s (an absent value resolves to opaque black on the renderer, an invisible highlight behind a 200). glow, scale_pop, slide_up and fly_in do not use it. A text element takes exactly one animation route: motion[], or word_animation, or animation_preset. Combining word_animation (or animation_preset) with motion[] is a 422 — the engine reads the word object only when no animations array is emitted, and its word timings would re-time the motion entries.
• Text is a different renderer. These are 422s on text: border_radius ≠ 0 (put the text over a rounded shape card), static x_rotation/y_rotation (tilt only via a custom_animations keyframe rotation: {x, y, z}), x_anchor/y_anchor other than "50%" (text rotates about its box centre), and text_decoration: "underline" / "strikethrough" (use a per-word style.underline in words[], or draw a thin shape rule). background, stroke and shadow select one renderer display mode, so setting two of them is a 422 — pick one. An element carrying a counter also rejects per-glyph animation (a per-glyph animation_preset, or a scope: "character" motion): glyph timings are computed once against the starting value, so later glyphs of longer numbers never render — animate a counter with a block preset (fade, scaleIn).
• Sources: a video source_url must end .mp4, .mov or .webm — any other extension is a 422 at submit, so re-encode first. Audio: use AAC/M4A/MP3. Give the audio element an explicit out_point; keep it ≤ the composition duration.
• A solid or gradient card/bar is a shape with a rectangular path ("M0 0 H100 V100 H0 Z", rounded with corner_radius) and a fill — a hex colour, a Gradient object ({kind, angle_degrees, stops}, ≥2 stops), or a CSS linear-gradient(...) / radial-gradient(...) string, which the API normalizes into the Gradient object at validation. This is the only spelling: the gradient element was removed and {"type": "gradient"} is a 422 whose message names shape and carries the JSON to send instead. A flat card is the same shape with a hex fill. Full-frame overlays: x/y "50%", width/height "100%".
• A gradient fill is just a paint: any path, plus everything else on the element. It sits where a flat hex colour would sit, on the shape’s own path — so a triangle, a blob or an icon outline takes a gradient as readily as the card’s rectangle, and the same element can also carry stroke/stroke_width/stroke_dash (a gradient shape outlined in a flat colour), path_keyframes (morph a gradient-filled path), trim/trim_keyframes (draw it on), and the compositing family — blend_mode, mask_shape/mask/mask_keyframes, matte, backdrop_blur. fill_rule, corner_radius and opacity behave exactly as with a flat fill. Two stacked shapes — a gradient one behind a flat one — remain a good way to build a layered look when you want two layers.
• Transparent output: alpha: true requires output_format "webm" or "mov" — with mp4 it is a 422. With alpha on, background_color is ignored and the wire background is forced fully transparent, so an alpha export cannot also carry a coloured backdrop; if you need one, draw it as a full-frame shape. Everything else composites normally.
• Transitions are video-to-video only. Both from_id and to_id must name visible video elements — a transition onto an image, text or shape is rejected (it crashes the render node). Each clip may be the outgoing side of at most one transition and the incoming side of at most one. {"type": "cross_dissolve", "duration": 0.8, "from_id": "clip1", "to_id": "clip2"} with clip2’s time at the boundary. To cross-fade stills, animate opacity with fade motions instead.
• Speed ramps: playback_rate_keyframes on a video are piecewise-linear time/rate points in absolute timeline seconds (rate 0 = freeze), at most 512, and the times must be strictly increasing — for an instant step put the two rates t and t + 0.001 apart. The audio inside the clip keeps the static rate, so mute the video element (volume: 0, legal there) or move the sound to its own audio element. A ramp ending at rate 0 needs an explicit request-level duration to say when the freeze stops, otherwise it is rejected. An audio element cannot be muted at all — its volume must be

  0; delete it instead (visible: false drops the track, it is not a mute).

• Masks: mask_shape ("circle", …) clips the element; mask (with scale, center) sizes it (scale ≈ 0.15 = small iris, ≈ 2.0 covers the frame); mask_keyframes animates it over time. Masks, blend_mode, matte and backdrop_blur exist on video, image and shape only — on text they are unknown fields and the request 422s with Extra inputs are not permitted. For text blends use the motion presets overlay / difference; for a masked or blended card, put the text over a shape.
• Shadows and radii use four different scales. On video/image, shadow_x/shadow_y and border_radius are real pixels — but a shadow whose offset is 0,0 is rejected outright (the renderer skips the pass entirely, so set at least 1px). On shape, shadow.distance/blur are the engine’s 0–100 strength scale (reference scenes author 60–70; a px-looking 8 renders under a pixel on a small card) and corner_radius is already a 0–1 fraction of half the shorter side, where 1.0 is a pill. Percentage strings are rejected on every pixel-unit field (border_radius, border_width, shadow_x, shadow_y, backdrop_blur) — pass a number or "Npx". On text, shadow_x/shadow_y/shadow_blur are a scale of their own again — pixels normalized against the canvas, neither the 0–100 strength of shape nor the border-grown pixels of video/image — so author them as a few px of offset and a blur in the tens, and never carry a card’s distance: 60 onto a text element.
• 3D tilt on video, image and shape: x_rotation/y_rotation accept degree strings ("18°" or "18deg"). Animate the tilt — and tilt text at all — with a custom_animations definition whose keyframes carry rotation: {x, y, z}, bound via motion: [{"custom": "<name>", ...}].
• A custom_animations keyframe time is a 0–1 fraction of the animation, not seconds (0 = start, 1 = end); the wall-clock window comes from the motion[] entry’s time/duration that binds it. Every other keyframe list — mask_keyframes, playback_rate_keyframes, path_keyframes, trim_keyframes, intensity_keyframes, word_animation.words[] — is in absolute timeline seconds. (counter.start_time is a third unit: seconds into the element.)
• Accepted but inert — do not build on these. text.opacity is never emitted (fade text with a fade motion, not a static opacity). motion[].easing is ignored — curves are baked into the preset, or into your custom_animations keyframes’ own easing. x_scale/y_scale, aspect_ratio, clip, name and track cross nowhere; size with width/height. lut_url/lut_intensity are accepted on image but applied only on video — grade a still with temperature/tint/vibrance/ highlights/shadows, or bake it in. flip_horizontal/flip_vertical cross only on video and image (mirror a shape by rewriting its path). On text, background_opacity, x_padding and y_padding cross nowhere: use an 8-digit background_color ("#000000aa") for a translucent plate, and pad by widening width or setting the text over a shape card. (color_overlay is the opposite case — it is rejected outright; tint with a blend-moded overlay element.)
• image and shape elements require a non-empty id and a duration. text requires duration; an id is optional there, but give every element a unique one anyway — duplicates are a blocking DUPLICATE_ELEMENT_ID, and transitions, groups, mattes and ops all address elements by id.

​

A minimal composition

{
  "width": 1920,
  "height": 1080,
  "duration": 6,
  "background_color": "#0B1B3AFF",
  "elements": [
    {
      "type": "text",
      "id": "headline",
      "text": "Meet Lumen",
      "time": 0,
      "duration": 6,
      "x": "50%",
      "y": "46%",
      "font_size": 120,
      "font_weight": 700,
      "text_color": "#FFFFFF",
      "motion": [{ "type": "fade", "time": 0, "duration": 1 }]
    }
  ]
}

​

A gradient card

{
  "type": "shape",
  "id": "hero_card",
  "time": 0,
  "duration": 6,
  "x": "50%",
  "y": "50%",
  "width": "62%",
  "height": "34%",
  "path": "M0 0 H100 V100 H0 Z",
  "corner_radius": 0.18,
  "fill": {
    "kind": "linear",
    "angle_degrees": 45,
    "stops": [
      { "offset": 0, "color": "#e07a4f" },
      { "offset": 1, "color": "#7c3aed" }
    ]
  },
  "shadow": { "color": "#00000066", "distance": 65, "direction": 90, "blur": 60 }
}

{
  "type": "shape",
  "id": "hero_card",
  "time": 0,
  "duration": 6,
  "x": "50%",
  "y": "50%",
  "width": "62%",
  "height": "34%",
  "path": "M0 0 H100 V100 H0 Z",
  "corner_radius": 0.18,
  "fill": "linear-gradient(45deg, #e07a4f 0%, #7c3aed 100%)"
}

​

Beyond the basics — what else the engine draws

• shape — an SVG d path with fill/stroke/dash, where the fill is a hex colour, "none", a Gradient object or a CSS linear-gradient(...) string, so a gradient card is a rectangular path with a gradient fill; trim + trim_keyframes draw it on (trim applies before dash, so a dashed line draws on without the pattern re-flowing), path_keyframes morph it.
• groups[] — transform several elements as one (translate/scale/rotate/3D tilt, a row/column stack layout, and their own animations[]); group opacity is 0–1 while element opacity is 0–100.
• custom_animations — your own keyframed presets, bound with motion: [{"custom": "<name>"}]; the only way to tilt or 3D-rotate text. Name them distinctively: none, overlay, difference, any name a catalog animation already answers to (fade, pop, scale, bounce, typewriter, …) and duplicates within one registry are all rejected — the engine would silently run the catalog animation instead of yours. Binding: motion[].custom resolves only against this request’s registry (an unknown name is a 422, not a silent drop), takes no reversed: true (author the exit as its own entry) and no scope: "character" (put group: "glyph" or "word" on the definition instead).
• matte — drive one layer’s coverage from another layer’s render; the source layer is auto-hidden.
• text.counter / text.glow / text.words[] — animated numbers, em-relative glow, per-word colour/bold/underline runs.
• motion[].audio — beat/bass-reactive offsets on video/image/shape and groups (never text); pair with type: "identity" for a pure generator.
• effects[] — a shader chain of 47 named effects, on video, image and shape alike. intensity is 0–100, but intensity_keyframes are {time, value} with time in absolute timeline seconds and value on a 0–1 scale, not 0–100 — a value above 1 is a 422. Two rules: props is whitelisted per shader and only aurora binds one ({"speed": n}) — any other key on aurora, and any prop at all on any other shader, is a 422, because the renderer would bind nothing and silently no-op. And chroma_key takes its parameters through chroma_settings (key_color, threshold, smoothness, spill_suppress), never props — it is the one shader that builds its own props block, so a props you set on it is silently discarded rather than rejected. Leave its intensity unset for a full key, since an explicit 50 leaves a translucent green wash.
• motion_blur, background_gradient, blend_mode, backdrop_blur — request- and element-level.

​

Named text animations (animation_preset)

​

Validate before you render

• OUT_OF_FRAME — an element’s box falls partly or fully off-canvas.
• ELEMENT_OUT_OF_RANGE — an element starts at/after the output duration and the renderer drops it.
• DUPLICATE_ELEMENT_ID — two elements share an id; transition targets and ops that address it become ambiguous. Rename one. (error)
• DANGLING_TRANSITION — a transition from_id/to_id matches no element. (error)
• TRANSITION_SELF — from_id equals to_id. (error)
• WORD_OUT_OF_RANGE — a word_animation.words[] timing falls outside the element’s [time, time + duration] window; word timings are absolute, not element-relative.
• ENTRANCE_AFTER_ELEMENT_START — an element’s entrance motion starts after the element itself, so it sits fully rendered on screen and then plays its entrance. Set motion[].time (and delay) to the element’s own time.
• AUDIO_HIDDEN — visible: false on an audio element removes the track from the render; it is not a mute.
• SHADOW_BELOW_MIN_SIZE — shadow.distance is a 0–100 strength, not pixels, and this value renders an offset under one pixel.