Movie#

Type: object

The movie object is the top-level structure submitted to POST /v2/movies. It defines the canvas, the playback timeline (scenes), any global elements that overlay every scene, the export destinations, and arbitrary client-side metadata.

Required properties#

• scenes

Properties#

audio-track#

Set to true to also export the movie's audio track as an MP3 file. The MP3 has the full mix of the movie (voices, music and the audio of its videos) and the same length as the video.

Its URL is returned as audio_url by GET /v2/movies. When the property is not set, audio_url is null.

Available on paid plans. On the free plan the property is accepted and ignored: the movie renders normally and audio_url is null.

The audio file is deleted together with the video: after 7 days, or immediately on DELETE /v2/movies.

cache#

If true, the rendered output is reused when the same input has been rendered before. If false, the render runs from scratch.

client-data#

Key-value pairs returned verbatim in GET /v2/movies responses and in webhook payloads. Use it to correlate a render with your own record IDs. Values can be any valid JSON type.

Property name. The hyphenated client-data is the correct form. client_data (underscore) is not accepted.

comment#

Free-form note attached to the movie. Ignored by the renderer.

elements#

Elements that overlay every scene. Stacking order in the array determines layering — later items render on top. If the movie has no scenes, these movie-level elements are rendered on their own as a single scene.

Array items#

Each item is one of the element types defined in Element. The discriminator is the type field.

exports#

Destinations for the rendered movie. Each item describes one export pipeline; multiple items run sequentially.

Array items#

fps#

Frames per second of the output video.

height#

Height of the movie in pixels. Required and applicable only when resolution is custom. Range: 50–3840. Bound by the account plan's maximum resolution.

id#

Unique identifier for the movie. Auto-generated when omitted.

preload#

List of assets to fetch or generate before the main render. Each preload item must have a unique id referenced from elements as {{id_url}}, {{id_duration}}, {{id_width}}, or {{id_height}}.

quality#

Render quality. Lower quality renders faster.

resolution#

Movie size. custom requires width and height.

scenes#

Ordered sequence of scenes that make up the movie. Optional — if omitted or empty, any movie-level elements are rendered on their own as a single scene.

Array items#

Each item is a Scene object.

template#

ID of a saved template to use as the movie body. When set, the template's movie is loaded and the request's variables are merged on top. resolution, width, height, quality, exports, and client-data from the request override the template.

thumbnail#

Timecode, in seconds, of the frame used as the movie thumbnail. Every render produces one automatically — set this property only to pick a different frame.

A negative value counts back from the end of the movie: -2 means 2 seconds before the end. The value is clamped to the movie duration, so a thumbnail at 2 on a 1.5-second movie, or at -30 on a 5-second movie, still returns a real frame.

The image is written next to the rendered video at full resolution, and its URL is returned as thumbnail by GET /v2/movies and in the webhook payload. It is a JPEG, except for movies rendered with a transparent background, which produce a PNG that keeps the alpha channel — read the URL rather than assuming the extension.

The thumbnail is deleted together with the video: after 7 days, or immediately on DELETE /v2/movies.

variables#

Key-value pairs used to interpolate {{name}} placeholders in strings throughout the movie. Variable names should use only letters, numbers, and underscores — other characters are silently replaced with underscores, and names starting with ?, $, or @ are silently dropped (no validation error is raised).

width#

Width of the movie in pixels. Required and applicable only when resolution is custom. Range: 50–3840. Bound by the account plan's maximum resolution.

draft#

Deprecated. Ignored by the renderer; watermarking is now controlled automatically by the account plan.