Image element
Places an image on the canvas — either a URL you host (`src`) or an AI-generated image (`generate`). Provide exactly one of the two.
Places an image on the canvas — either a URL you host (src) or an AI-generated image (generate). Provide exactly one of the two.
Properties
| Property | Type | Default | Description |
|---|---|---|---|
id * | string (non-empty) | — | Stable identifier, unique across the whole movie. Used by editor selection sync and error paths. |
start | number (≥ 0) | 0 | When the element appears, in seconds relative to its scene (or to the movie for movie-level elements). |
duration | number (> 0) | — | How long the element is active, in seconds. Defaults to the remainder of its scene. |
position | object | "top-left" | "top-center" | "top-right" | "center-left" | "center" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right" | "center" | Where to place the element: absolute {x, y} pixels or a named anchor. |
width | number (> 0) | — | Element box width in output pixels. Defaults to an element-specific intrinsic size. |
height | number (> 0) | — | Element box height in output pixels. Defaults to an element-specific intrinsic size. |
opacity | number (0–1) | 1 | Element opacity from 0 (invisible) to 1 (fully opaque). |
rotation | number | 0 | Rotation around the element's center, in degrees (clockwise). |
animation | object | — | Entrance animation applied when the element appears. |
type * | "image" | — | A static image from a URL or generated by AI. |
src | string (non-empty) | — | Image source URL. Provide exactly one of "src" or "generate". |
generate | object | — | AI image generation request, used instead of a source URL. |
fit | "cover" | "contain" | "fill" | "cover" | How the media scales to its box: cover crops to fill it, contain letterboxes inside it, fill stretches to it. |
position object
Absolute pixel position of the element's center.
| Property | Type | Default | Description |
|---|---|---|---|
x * | number | — | Horizontal position of the element's center, in output pixels from the left edge. |
y * | number | — | Vertical position of the element's center, in output pixels from the top edge. |
animation object
Entrance animation applied when the element appears.
| Property | Type | Default | Description |
|---|---|---|---|
preset * | "none" | "fade" | "slide-in-left" | "slide-in-right" | "slide-in-up" | "slide-in-down" | "zoom-in" | "zoom-out" | — | Entrance animation preset applied when the element appears. |
easing | "linear" | "ease" | "ease-in" | "ease-out" | "ease-in-out" | "ease" | Easing curve applied to the animation. |
duration | number (> 0) | 0.5 | Animation duration in seconds. |
generate object
AI image generation request, used instead of a source URL.
| Property | Type | Default | Description |
|---|---|---|---|
prompt * | string (non-empty) | — | Prompt for AI image generation. May contain {{variable}} placeholders. |
style | string (non-empty) | — | Optional style hint passed to the image model, e.g. "photographic". |
seed | integer (≥ 0) | — | Seed for reproducible generations. Identical requests are served from cache. |
Example
Image: a URL image plus an AI-generated background: