Top level
| Field | Type | What it does |
|---|---|---|
schemaVersion * | 1 | Timeline schema version. Always 1. |
output * | object | |
output.format | "mp4" | "webm" | "gif" | "mp3" | "jpg" | "png" | Output container/format. mp4=H.264+AAC, webm=VP9+Opus, gif=animated (no audio), mp3=audio only and needs no size, jpg/png=single frame. default "mp4". |
output.size | "360p" | "720p" | "1080p" | "1440p" | "4k" | "tiktok" | "reels" | "shorts" | "instagram-story" | "instagram-feed" | "square" | "youtube-hd" | "youtube-4k" | "x-landscape" | "linkedin" | Named resolution preset (dimensions only): a generic ladder (“1080p”, “4k”) or a platform alias (“tiktok”, “reels”, “youtube-4k”). An explicit resolution overrides this. Not used by mp3. |
output.resolution | object | Explicit output dimensions. Wins over size. Every format but mp3 needs this or size. |
output.fps | number | Output frame rate. Defaults to 30. default 30, over 0. |
output.quality | "draft" | "standard" | "high" | "max" | Encoder quality ladder (crf + speed + audio bitrate). draft=fast preview, standard=web delivery (default), high/max=higher fidelity, slower. Explicit crf/encoderPreset override the ladder. default "standard". |
output.videoCodec | "h264" | "vp9" | The video codec. mp4 takes h264 (default) or vp9. webm is always vp9. gif is always GIF, so it takes none. |
output.audioCodec | "aac" | "opus" | "mp3" | The audio codec. mp4 takes aac (default), opus or mp3. webm is always opus and mp3 always mp3. |
output.crf | integer | Advanced: constant rate factor (lower = higher quality/larger file). Overrides quality. h264 accepts 0-51, vp9 0-63. Does not apply to gif/mp3/jpg/png. min 0, max 63. |
output.encoderPreset | "ultrafast" | "superfast" | "veryfast" | "faster" | "fast" | "medium" | "slow" | "slower" | "veryslow" | Advanced: x264 speed/compression preset (slower = smaller file, same quality). Overrides quality. h264 only. |
output.range | object | Which part of the timeline to render: a preview, or one section checked without paying for the whole render. A jpg or png is the single frame at start, the first frame when there is no range. |
timeline * | object | The edit itself, in ONE of two shapes: { tracks } for precise multi-track control (layers, exact timing), or { scenes, overlays } for sequential scene-by-scene authoring. Not both. |
prompt | string | The natural-language request this timeline was generated from, when AI assist was used. |
assets | string[] | The asset URLs supplied to AI assist, when it was used. |
Timeline
| Field | Type | What it does |
|---|---|---|
background | string | "transparent" | The colour behind every clip, wherever nothing else is drawn, like “#FFFFFF”. Defaults to black. “transparent” leaves those parts see-through, for png and webm output: a title or a lower third to lay over other video. |
effects | object[] | Effects on the finished picture and the final mix, after every track is composited: one grade over the whole video, or a limiter on the master. |
tracks | object[] | Layer stack: the FIRST track is the background, each later track composites on top (overlays, picture-in-picture, titles). Within a track, clips play in time; between two clips a transition item blends them. |
tracks.name | string | Optional label for your own reference, not rendered. |
tracks.effects | object[] | Effects on the whole track, after its clips are laid out: grade every clip on it at once, or put a limiter on a music track. |
tracks.clips * | object[] | Clips in time order, with optional transition items between adjacent clips. Omit start and length and they lay themselves out end to end, each as long as its source, overlapping by any transition between them. Text and image clips have no source, so they run to the end of the video and must come last on their track. |
scenes | object[] | Sequential segments played one after another, each with its own clips and an optional transition into it. |
scenes.duration | number | Scene length in seconds. Omit to take it from the longest thing inside: a clip’s own length, or the source in it. over 0. |
scenes.transition | object | The transition INTO this scene from the previous one. Omit on the first scene and for hard cuts. |
scenes.clips * | object[] | Clips layered within this scene: first is the background, later clips composite on top. |
overlays | object[] | Clips composited over the WHOLE video regardless of scenes: a logo, a watermark, a persistent title. The whole video is their container, so omitting length spans it. start defaults to 0. |
overlays.asset * | object | |
overlays.start | number | When the clip begins, in seconds from the start of the video. Omit it and the clip starts after everything already placed on its track, pulled back by any transition sitting immediately before it. The first clip on a track starts at 0. min 0. |
overlays.length | number | "end" | How long the clip plays. Omit it and the clip runs as long as its CONTENT does: the trim span, the source duration divided by speed, or a composition’s own end. Use “end” and it runs to the end of the video instead, whatever the source says, which is what a music bed wants. Text and images have no duration of their own, so omitting is the same as “end” for them and a title with no length stays up. A clip that runs to the end must be the last on its track. A video, audio or animation clip that runs past the end of its file holds the last frame, silent, until the clip ends, and the job says which clip in the render step’s clipOverruns. |
overlays.opacity | number | object[] | Clip opacity: a constant 0..1, or keyframes [{time, value, easing}] for animated fades. Fade a clip in with [{time:0,value:0},{time:1,value:1}]. default 1. |
overlays.transform | object | Position/scale/rotate the clip within the frame (picture-in-picture, Ken Burns). Omit for full-frame. |
overlays.crop | object | Trim edges off the frame by percent; the kept region scales back up to fill. Use to reframe landscape footage for a vertical canvas, and radius to round its corners. |
overlays.speed | number | Playback rate: 0.5 = slow motion, 2 = timelapse. Pitch shifts with speed. Not allowed on composition clips. Avoid slow motion on the OUTGOING side of a transition (it can run out of frames). over 0. |
overlays.effects | object[] | What is done to the clip’s picture or sound: one ordered list, each entry an object with a “type”. Picture effects run in the order listed, and so do sound effects. Any entry takes “start” and “length” (seconds, or a percent of the clip) to run for part of the clip, and a number parameter marked animatable takes keyframes. Effects: chromaKey(color, similarity): Remove a solid background colour (green screen); color(brightness, contrast, saturation, gamma, hue, temperature): Grade the picture by hand; look(name): A one-word look: greyscale, boost (vivid social pop), muted (desaturated, cinematic), lighten and darken (exposure), contrast, negative, sepia (brown archive tone), oldFilm (sepia with grain, dust, scratches, projector flicker and a vignette); blur(radius): Soften the picture; sharpen(amount): Crisp up soft footage; denoise(amount): Clean the grain a small sensor adds in low light; glow(amount): Make the bright parts of the picture bloom; grain(amount): A layer of film grain, so digital footage feels less clinical; lut(src): Grade the picture with a 3D LUT, the .cube file a colourist or a grading app exports; vignette(amount, radius): Darken the corners to pull the eye to the middle of the frame; shake(amount, speed): Handheld camera energy on a steady shot; glitch(amount): Digital break-up: blocks of the picture jump sideways and the colours tear; pixelate(size): Large square pixels over the whole picture; posterize(levels): Flatten the picture into a few steps of each colour, like a screen print; rgbShift(distance): Pull the red and blue channels apart sideways, for a chromatic, analogue-video edge; scanLines(): The dark horizontal lines of a CRT monitor; sketch(amount): Turn the picture into a pencil drawing; trails(duration): Blend the last moments of the clip together, so moving lights and people leave streaks; blurRegion(x, y, width, height, shape, radius): Blur one part of the picture and leave the rest sharp: a face, a number plate, a logo, a screen; mask(src, channel): Show the clip only where an image says: white or opaque keeps it, black or clear cuts it away, grey fades it; outline(color, width): A stroke round the edge of a layer that has transparency: a keyed subject, a picture in picture, a logo; dropShadow(color, opacity, blur, offsetX, offsetY): A soft shadow under a layer that has transparency, so a logo, a cut-out or a picture in picture lifts off what is behind it; visualizer(kind, color, x, y, width, height): Draw the sound over the picture: the audiogram look; eq(bass, mid, treble): Three-band tone control; compressor(threshold, ratio, makeup): Even out a voice, so quiet words and loud words sit at one level; limiter(gain, ceiling): Stop peaks from clipping; gate(threshold): Close the microphone between phrases, so room noise drops away in the pauses; highPass(cutoff): Cut everything below a frequency; lowPass(cutoff): Cut everything above a frequency; loudness(target): Bring sound to a standard loudness, riding the level as it goes; pitch(semitones): Raise or lower the pitch without changing the speed; echo(delay, amount): A repeat behind the sound; reverb(amount): Place a dry voice in a hall; voiceDenoise(amount): Remove steady background noise from under speech: a river, a fan, a street; engine(service, params): any other engine filter by the engine’s own names, strictly typed ones only. |
overlays.blendMode | "normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "add" | "difference" | How this clip mixes with the layer below: screen for light leaks/glows, multiply for darkening textures, overlay for contrast looks, add/lighten/darken/difference for effects. Meaningful on overlay tracks. |
overlays.pan | number | Stereo balance: -1 full left, 0 centered, 1 full right. min -1, max 1. |
overlays.flip | object | Mirror the clip horizontally and/or vertically. |
Track
| Field | Type | What it does |
|---|---|---|
name | string | Optional label for your own reference, not rendered. |
effects | object[] | Effects on the whole track, after its clips are laid out: grade every clip on it at once, or put a limiter on a music track. |
clips * | object[] | Clips in time order, with optional transition items between adjacent clips. Omit start and length and they lay themselves out end to end, each as long as its source, overlapping by any transition between them. Text and image clips have no source, so they run to the end of the video and must come last on their track. |
Clip
Every clip takes these, whatever its asset.| Field | Type | What it does |
|---|---|---|
start | number | When the clip begins, in seconds from the start of the video. Omit it and the clip starts after everything already placed on its track, pulled back by any transition sitting immediately before it. The first clip on a track starts at 0. min 0. |
length | number | "end" | How long the clip plays. Omit it and the clip runs as long as its CONTENT does: the trim span, the source duration divided by speed, or a composition’s own end. Use “end” and it runs to the end of the video instead, whatever the source says, which is what a music bed wants. Text and images have no duration of their own, so omitting is the same as “end” for them and a title with no length stays up. A clip that runs to the end must be the last on its track. A video, audio or animation clip that runs past the end of its file holds the last frame, silent, until the clip ends, and the job says which clip in the render step’s clipOverruns. |
opacity | number | object[] | Clip opacity: a constant 0..1, or keyframes [{time, value, easing}] for animated fades. Fade a clip in with [{time:0,value:0},{time:1,value:1}]. default 1. |
transform | object | Position/scale/rotate the clip within the frame (picture-in-picture, Ken Burns). Omit for full-frame. |
transform.position | object | object[] | Where to place the clip, in pixels like {x:1600,y:900} or percent like {x:“75%“,y:“75%”}, or keyframes of them to move it. Omit it and the clip is centred, so a scale of 0.5 alone is a centred picture-in-picture. |
transform.scale | number | object[] | Size relative to the frame: 1 = full frame, 0.3 = a corner PiP, above 1 zooms in (crops edges). Keyframes animate it: [{time:“0%“,value:1,easing:“easeInOutSine”},{time:“100%“,value:1.15}] is a Ken Burns push-in. A keyframe’s easing shapes the move into the next one. default 1. |
transform.rotate | number | object[] | Rotation in degrees, clockwise. Keyframes spin it. default 0. |
transform.anchor | "center" | "topLeft" | What position points at: the clip’s center (default) or its top-left corner. It is also what the clip turns about. With no position the clip is centred either way. On text, x follows style.align, so anchor only decides whether y is the text’s middle or its top edge. default "center". |
transform.fit | "contain" | "cover" | "fill" | "blur" | How a picture fills its box when their shapes differ: contain shows all of it, cover fills the box and cuts what overflows (a vertical phone clip in a 16:9 frame with no bars), fill stretches it, blur shows all of it over an enlarged, blurred copy that fills the bars, for a clip that fills the frame. The box is size, or the frame. default "contain". |
transform.size | object | object[] | The clip’s box, in pixels like {width:480,height:480} or a percent of the frame. Omit it and the box is the whole frame. A picture fills it the way fit says: {width:400,height:400} with fit “cover” is a square cut from 16:9 footage. A shape is drawn to it: {width:“100%“,height:“12%”} is a lower-third bar. Give one side and the clip keeps its own shape, which for a shape is SQUARE IN PIXELS, the only way to a true circle on a 16:9 frame. scale then multiplies the box, for zooms. Keyframes resize it: a width from “0%” to “80%” is a progress bar. |
transform.corners | object | object[] | Pins the clip’s four corners to four points, in pixels or percent: a picture on a screen, a sign seen in perspective. It is the other form of a transform, so it is not combined with position, scale, rotate or fit. A corner may sit up to a frame beyond each edge. Keyframes move the corners. |
crop | object | Trim edges off the frame by percent; the kept region scales back up to fill. Use to reframe landscape footage for a vertical canvas, and radius to round its corners. |
crop.top | string | Percent of the frame height to remove from the top. default "0%", pattern ^-?\d+(\.\d+)?%$. |
crop.right | string | Percent of the frame width to remove from the right. default "0%", pattern ^-?\d+(\.\d+)?%$. |
crop.bottom | string | Percent of the frame height to remove from the bottom. default "0%", pattern ^-?\d+(\.\d+)?%$. |
crop.left | string | Percent of the frame width to remove from the left. default "0%", pattern ^-?\d+(\.\d+)?%$. |
crop.radius | number | Rounds the corners of what is kept, 0 to 1. 1 rounds the shorter side fully, a pill. The corners ride the transform, so a scaled-down clip becomes a rounded picture-in-picture. The kept part fills the frame, so radius 1 is only a circle on a square frame. min 0, max 1. |
speed | number | Playback rate: 0.5 = slow motion, 2 = timelapse. Pitch shifts with speed. Not allowed on composition clips. Avoid slow motion on the OUTGOING side of a transition (it can run out of frames). over 0. |
effects | object[] | What is done to the clip’s picture or sound: one ordered list, each entry an object with a “type”. Picture effects run in the order listed, and so do sound effects. Any entry takes “start” and “length” (seconds, or a percent of the clip) to run for part of the clip, and a number parameter marked animatable takes keyframes. Effects: chromaKey(color, similarity): Remove a solid background colour (green screen); color(brightness, contrast, saturation, gamma, hue, temperature): Grade the picture by hand; look(name): A one-word look: greyscale, boost (vivid social pop), muted (desaturated, cinematic), lighten and darken (exposure), contrast, negative, sepia (brown archive tone), oldFilm (sepia with grain, dust, scratches, projector flicker and a vignette); blur(radius): Soften the picture; sharpen(amount): Crisp up soft footage; denoise(amount): Clean the grain a small sensor adds in low light; glow(amount): Make the bright parts of the picture bloom; grain(amount): A layer of film grain, so digital footage feels less clinical; lut(src): Grade the picture with a 3D LUT, the .cube file a colourist or a grading app exports; vignette(amount, radius): Darken the corners to pull the eye to the middle of the frame; shake(amount, speed): Handheld camera energy on a steady shot; glitch(amount): Digital break-up: blocks of the picture jump sideways and the colours tear; pixelate(size): Large square pixels over the whole picture; posterize(levels): Flatten the picture into a few steps of each colour, like a screen print; rgbShift(distance): Pull the red and blue channels apart sideways, for a chromatic, analogue-video edge; scanLines(): The dark horizontal lines of a CRT monitor; sketch(amount): Turn the picture into a pencil drawing; trails(duration): Blend the last moments of the clip together, so moving lights and people leave streaks; blurRegion(x, y, width, height, shape, radius): Blur one part of the picture and leave the rest sharp: a face, a number plate, a logo, a screen; mask(src, channel): Show the clip only where an image says: white or opaque keeps it, black or clear cuts it away, grey fades it; outline(color, width): A stroke round the edge of a layer that has transparency: a keyed subject, a picture in picture, a logo; dropShadow(color, opacity, blur, offsetX, offsetY): A soft shadow under a layer that has transparency, so a logo, a cut-out or a picture in picture lifts off what is behind it; visualizer(kind, color, x, y, width, height): Draw the sound over the picture: the audiogram look; eq(bass, mid, treble): Three-band tone control; compressor(threshold, ratio, makeup): Even out a voice, so quiet words and loud words sit at one level; limiter(gain, ceiling): Stop peaks from clipping; gate(threshold): Close the microphone between phrases, so room noise drops away in the pauses; highPass(cutoff): Cut everything below a frequency; lowPass(cutoff): Cut everything above a frequency; loudness(target): Bring sound to a standard loudness, riding the level as it goes; pitch(semitones): Raise or lower the pitch without changing the speed; echo(delay, amount): A repeat behind the sound; reverb(amount): Place a dry voice in a hall; voiceDenoise(amount): Remove steady background noise from under speech: a river, a fan, a street; engine(service, params): any other engine filter by the engine’s own names, strictly typed ones only. |
blendMode | "normal" | "multiply" | "screen" | "overlay" | "darken" | "lighten" | "add" | "difference" | How this clip mixes with the layer below: screen for light leaks/glows, multiply for darkening textures, overlay for contrast looks, add/lighten/darken/difference for effects. Meaningful on overlay tracks. |
pan | number | Stereo balance: -1 full left, 0 centered, 1 full right. min -1, max 1. |
flip | object | Mirror the clip horizontally and/or vertically. |
flip.horizontal | boolean | Mirror left-right. default false. |
flip.vertical | boolean | Mirror top-bottom. default false. |
* are required. Every table on this page is generated from the schema the API validates with, so it cannot drift from what a render accepts.