This page is the field-by-field reference for the elements[] array in POST /v1/renders. For full request body examples see the Render Examples section.
How to read this page
| Column | Meaning |
|---|
| required | The API returns 422 if the field is missing |
| optional | The field has a default and may be omitted |
→ 0 / → null | Default value the API uses when the field is omitted |
Dimension fields accept a pixel number (960), a percentage string ("50%"), or an angle string ("90°" / "90deg") depending on context.
Common fields
These fields are present on every element type.
| Field | Type | | Default | Description |
|---|
type | string (enum) | required | — | Element discriminator. One of: video, audio, text, image |
id | string | optional | → "" | Unique identifier. Required on image elements — an empty ID causes the image to be silently skipped. Recommended on all elements used in transitions. |
time | number ≥ 0 | optional | → 0 | When the element starts on the output timeline, in seconds. |
duration | number > 0 | see per-type | — | How long the element is active, in seconds. Required on text and image — omitting it produces a zero-length window and the element will not appear. Not accepted on video or audio — use out_point to control clip length. |
visible | boolean | optional | → true | Set to false to exclude from the render without removing from the request. |
name | string | optional | → null | Human-readable label. Not used by the renderer. |
track | integer 0–255 | optional | → null | Timeline track index. Informational only; not used by the renderer. |
video
Plays a video clip on the timeline.
Source and trim
| Field | Type | | Default | Description |
|---|
source_url | URL | required | — | URL of the video file. Must be accessible by the renderer. |
in_point | number ≥ 0 | optional | → 0 | Seconds into the source file to start playing from. |
out_point | number > 0 | optional | → end of source | Seconds into the source file to stop playing. Must be greater than in_point when both are set. |
speed | number 0.25–4.0 | optional | → 1.0 | Playback speed multiplier. 2.0 = 2× speed. |
Video elements do not have a duration field. Clip length on the output timeline is determined by out_point − in_point (accounting for speed). To fix the output to a specific length, set a top-level duration on the request.
Position and size
| Field | Type | | Default | Description |
|---|
x | Dimension | optional | → "50%" | Horizontal center position. |
y | Dimension | optional | → "50%" | Vertical center position. |
width | Dimension | optional | → "100%" | Clip width. |
height | Dimension | optional | → "100%" | Clip height. |
z_index | integer | optional | → 0 | Stacking order. Higher numbers appear in front. |
opacity | number 0–100 | optional | → 100 | Transparency percentage. |
z_rotation | Dimension | optional | → "0°" | Rotation around the Z axis. |
flip_horizontal | boolean | optional | → false | Mirror horizontally. |
flip_vertical | boolean | optional | → false | Mirror vertically. |
Audio
| Field | Type | | Default | Description |
|---|
volume | number 0–100 | optional | → 100 | Embedded audio volume percentage. Affects only the audio track inside this clip. |
fade_in_duration | number | optional | → 0 | Seconds of linear audio fade-in at the clip start. |
fade_out_duration | number | optional | → 0 | Seconds of linear audio fade-out at the clip end. |
Color adjustments
| Field | Type | | Default | Description |
|---|
brightness | number | optional | → 0 | Brightness offset. |
contrast | number | optional | → 0 | Contrast offset. |
saturation | number | optional | → 0 | Saturation offset. |
exposure | number | optional | → 0 | Exposure offset. |
sharpness | number | optional | → 0 | Sharpening amount. |
blur | number | optional | → 0 | Gaussian blur radius in pixels. |
noise | number | optional | → 0 | Film grain amount. |
vignette | number | optional | → 0 | Vignette intensity. |
hue_rotate | number | optional | → 0 | Hue rotation in degrees. |
lut_url | URL | optional | → null | URL of a .cube LUT file. |
lut_intensity | number 0–100 | optional | → 100 | LUT blend percentage. |
Cropping
| Field | Type | | Default | Description |
|---|
crop_top | number 0–1 | optional | → 0 | Fraction of the clip to crop from the top edge. |
crop_bottom | number 0–1 | optional | → 0 | Fraction of the clip to crop from the bottom edge. |
crop_left | number 0–1 | optional | → 0 | Fraction of the clip to crop from the left edge. |
crop_right | number 0–1 | optional | → 0 | Fraction of the clip to crop from the right edge. |
Border and shadow
| Field | Type | | Default | Description |
|---|
border_radius | Dimension | optional | → 0 | Corner radius in pixels. |
border_color | hex color | optional | → null | Border color. |
border_width | Dimension | optional | → 0 | Border thickness in pixels. |
shadow_color | hex color | optional | → null | Drop shadow color. Shadow is hidden when this is null. |
shadow_blur | Dimension | optional | → 0 | Shadow blur radius. |
shadow_x | Dimension | optional | → 0 | Shadow horizontal offset. |
shadow_y | Dimension | optional | → 0 | Shadow vertical offset. |
Effects, motion, AI
| Field | Type | | Default | Description |
|---|
effects | Effect[] | optional | → [] | Visual effects (chroma key, glitch, etc.). See Effect object. |
motion | Motion[] | optional | → [] | Entrance / exit / loop motion presets. See Motion object. |
remove_background | boolean | optional | → false | Remove video background using AI. Triggers a separate pre-processing task. |
gaze_redirect | boolean | optional | → false | Redirect on-screen gaze to face the camera using AI. |
super_resolution | number 1.0–4.0 | optional | → null | AI upscale factor. Triggers a separate pre-processing task. |
audio
Plays an audio clip or background music track.
| Field | Type | | Default | Description |
|---|
source_url | URL | required | — | URL of the audio file. |
time | number ≥ 0 | optional | → 0 | Start time on the output timeline in seconds. |
in_point | number ≥ 0 | optional | → 0 | Seconds into the source to start from. |
out_point | number > 0 | optional | → end of source | Seconds into the source to stop. Controls clip length on the output timeline. Must be greater than in_point when both are set. |
speed | number 0.25–4.0 | optional | → 1.0 | Playback speed multiplier. |
volume | number 1–100 | optional | → 100 | Volume percentage. Must be greater than 0 — the renderer silently drops audio streams with volume ≤ 0. |
fade_in_duration | number | optional | → 0 | Seconds of linear fade-in at the clip start. |
fade_out_duration | number | optional | → 0 | Seconds of linear fade-out at the clip end. |
text
Renders a text layer on screen.
duration is required on text elements. Omitting it produces a zero-length window — the text will not appear in the render.
| Field | Type | | Default | Description |
|---|
text | string | required | — | The text content to render. |
duration | number > 0 | required | — | How long the text is visible in seconds. |
time | number ≥ 0 | optional | → 0 | When the text appears on the output timeline. |
font_family | string | optional | → "Inter" | Font family name. Must be available to the renderer. |
font_size | number > 0 | optional | → 16 | Font size in pixels. |
font_weight | integer 100–900 | optional | → 400 | Font weight. 400 = regular, 700 = bold. |
font_style | normal | italic | bold | bolditalic | optional | → "normal" | Font style variant. |
text_color | hex color | optional | → "#ffffff" | Text fill color. |
text_align | left | center | right | optional | → "center" | Horizontal text alignment. |
text_decoration | none | underline | strikethrough | optional | → "none" | Text decoration. |
tracking | number | optional | → 0 | Extra spacing between characters. |
leading | number | optional | → 1.2 | Line height multiplier. |
stroke_color | hex color | optional | → null | Outline color. Set together with stroke_width to enable outlines. |
stroke_width | number | optional | → 0 | Outline width in pixels. Has no effect unless stroke_color is also set. |
background_color | hex color | optional | → null | Color of the background box (when background is true) or the active-word highlight (when using box or color word animations). |
background_opacity | number 0–100 | optional | → 100 | Background fill opacity. |
background | boolean | optional | → false | Solid color box behind the full text block. Set background_color to choose the color. |
stroke | boolean | optional | → false | Outline-only mode — draws the glyph stroke with no fill. Requires stroke_color and stroke_width. When false, setting stroke_color + stroke_width gives fill + stroke. |
shadow | boolean | optional | → false | Built-in drop shadow. |
text_wrap | wrap | nowrap | optional | → "wrap" | Whether long lines wrap. |
motion | Motion[] | optional | → [] | Entrance / exit / loop motion presets. See Motion object. |
animation_preset | string | optional | → null | Animation shorthand string (e.g. "typewriter"). Ignored when word_animation is set. |
word_animation | WordAnimation | optional | → null | Word-level animation with per-word timestamps. See WordAnimation object and word animation examples. |
x | Dimension | optional | → "50%" | Horizontal center position. |
y | Dimension | optional | → "50%" | Vertical center position. |
width | Dimension | optional | → "100%" | Text wrap width. |
z_index | integer | optional | → 1 | Stacking order. |
opacity | number 0–100 | optional | → 100 | Transparency percentage. |
z_rotation | Dimension | optional | → "0°" | Rotation around the Z axis. |
border_radius | Dimension | optional | → 0 | Corner radius of the fill background. |
shadow_color | hex color | optional | → null | Drop shadow color. |
shadow_blur | Dimension | optional | → 0 | Shadow blur radius. |
shadow_x | Dimension | optional | → 0 | Shadow horizontal offset. |
shadow_y | Dimension | optional | → 0 | Shadow vertical offset. |
image
Renders a static image on screen.
Both id and duration are required on image elements. An empty or missing id causes the image to be silently skipped by the renderer. A missing duration produces a zero-length window.
| Field | Type | | Default | Description |
|---|
id | string | required | — | Unique identifier. Empty string causes silent skip. |
source_url | URL | required | — | URL of the image file (PNG, JPG, WebP). |
duration | number > 0 | required | — | How long the image is visible in seconds. |
time | number ≥ 0 | optional | → 0 | When the image appears on the output timeline. |
x | Dimension | optional | → "50%" | Horizontal center position. |
y | Dimension | optional | → "50%" | Vertical center position. |
width | Dimension | optional | → "100%" | Image width. |
height | Dimension | optional | → "100%" | Image height. |
z_index | integer | optional | → 0 | Stacking order. Same default as video — set to 1 or higher when placing an image over a video clip. |
opacity | number 0–100 | optional | → 100 | Transparency percentage. |
z_rotation | Dimension | optional | → "0°" | Rotation around the Z axis. |
flip_horizontal | boolean | optional | → false | Mirror horizontally. |
flip_vertical | boolean | optional | → false | Mirror vertically. |
motion | Motion[] | optional | → [] | Entrance / exit / loop motion presets. |
effects | Effect[] | optional | → [] | Visual effects. |
brightness | number | optional | → 0 | |
contrast | number | optional | → 0 | |
saturation | number | optional | → 0 | |
exposure | number | optional | → 0 | |
sharpness | number | optional | → 0 | |
blur | number | optional | → 0 | Gaussian blur in pixels. |
noise | number | optional | → 0 | Film grain. |
vignette | number | optional | → 0 | |
hue_rotate | number | optional | → 0 | Hue rotation in degrees. |
lut_url | URL | optional | → null | .cube LUT file URL. |
lut_intensity | number 0–100 | optional | → 100 | LUT blend percentage. |
crop_top | number 0–1 | optional | → 0 | |
crop_bottom | number 0–1 | optional | → 0 | |
crop_left | number 0–1 | optional | → 0 | |
crop_right | number 0–1 | optional | → 0 | |
border_radius | Dimension | optional | → 0 | Corner radius in pixels. |
border_color | hex color | optional | → null | |
border_width | Dimension | optional | → 0 | |
shadow_color | hex color | optional | → null | |
shadow_blur | Dimension | optional | → 0 | |
shadow_x | Dimension | optional | → 0 | |
shadow_y | Dimension | optional | → 0 | |
Sub-objects
Motion
Used in motion[] on video, text, and image. These are pre-built motion presets — not keyframe animations.
| Field | Type | | Default | Description |
|---|
type | MotionType | required | — | Motion preset identifier (e.g. fade, slide_up, zoom_in). |
time | number ≥ 0 | required | — | Absolute start time on the output timeline in seconds. For entrances and loops use the element’s time. For exits use element time + duration − motion duration. |
duration | number > 0 | required | — | How long the preset runs in seconds. |
reversed | boolean | optional | → false | true = exit variant; false = entrance variant. |
easing | ease_in_out | ease_in | ease_out | linear | optional | → "ease_in_out" | Easing curve. |
scope | element | character | optional | → "element" | Apply to the whole element (element) or each character individually (character). Character scope is only supported on text. |
loop | boolean | optional | → false | Loop the preset for its duration. |
delay | number | optional | → 0 | Delay in seconds before starting when looping. |
Effect
Used in effects[] on video and image.
| Field | Type | | Default | Description |
|---|
type | EffectType | required | — | Effect identifier (e.g. chroma_key, glitch, vhs). |
intensity | number 0–100 | optional | → 50 | Effect strength percentage. |
chroma_props | ChromaKeyProps | optional | → null | Fine-tuned chroma key settings. Only used when type is chroma_key. |
ChromaKeyProps
| Field | Type | | Default | Description |
|---|
hue_min | number | optional | → 60 | Minimum hue of the color range to key out. |
hue_max | number | optional | → 180 | Maximum hue of the color range to key out. |
sat_min | number | optional | → 0.3 | Minimum saturation threshold. |
sat_max | number | optional | → 1.0 | Maximum saturation threshold. |
lum_min | number | optional | → 0.2 | Minimum luminance threshold. |
lum_max | number | optional | → 0.9 | Maximum luminance threshold. |
WordAnimation
Used as word_animation on text. Drives word-by-word animated text synchronized to timestamps.
| Field | Type | | Default | Description |
|---|
style | WordAnimationStyle | required | — | Animation style. One of: glow, box, scale_pop, slide_up, fly_in, color. |
words | Word[] | required | — | Per-word timestamps. Must be non-empty. |
Word
Used in word_animation.words[]. Timestamps are absolute timeline seconds — the same clock as the element’s time, motion time, and everything else.
| Field | Type | | Default | Description |
|---|
text | string | required | — | The word text. |
start | number ≥ 0 | required | — | Seconds from the text element’s start when this word begins. |
end | number > 0 | required | — | Seconds from the text element’s start when this word ends. |
