JSON2VIDEO Documentation 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
cache
If true, the rendered output is reused when the same input has been rendered before. If false, the render runs from scratch.
| Type | boolean |
| Required | No |
| Default Value | true |
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-datais the correct form.client_data(underscore) is not accepted.
| Type | object |
| Required | No |
| Default Value | {} |
comment
Free-form note attached to the movie. Ignored by the renderer.
| Type | string |
| Required | No |
elements
Elements that overlay every scene. Stacking order in the array determines layering — later items render on top.
| Type | array |
| Required | No |
Array items
Each item is one of the element types defined in Element. The discriminator is the type field.
type value |
Schema |
|---|---|
image |
Image element |
video |
Video element |
text |
Text element |
html |
HTML element |
component |
Component element |
audio |
Audio element |
voice |
Voice element |
audiogram |
Audiogram element |
subtitles |
Subtitles element |
exports
Destinations for the rendered movie. Each item describes one export pipeline; multiple items run sequentially.
| Type | array |
| Required | No |
Array items
| Property | Type | Description |
|---|---|---|
destinations |
array | One or more destination objects. Each destination has a type (webhook, ftp, sftp, email) and the fields it requires, OR an id referencing a Dashboard connection. See Webhooks for the webhook destination contract. |
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.
| Type | integer |
| Required | No |
| Default Value | 360 |
| Minimum Value | 50 |
| Maximum Value | 3840 |
id
Unique identifier for the movie. Auto-generated when omitted.
| Type | string |
| Required | No |
| Default Value | "@randomString" |
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}}.
| Type | array |
| Required | No |
quality
Render quality. Lower quality renders faster.
| Type | string |
| Required | No |
| Default Value | "high" |
| Enum Values | low, medium, high |
resolution
Movie size. custom requires width and height.
| Type | string |
| Required | No |
| Default Value | "custom" |
| Enum Values | sd, hd, full-hd, squared, instagram-story, instagram-feed, twitter-landscape, twitter-portrait, custom |
scenes
Ordered sequence of scenes that make up the movie. Required, may be empty.
| Type | array |
| Required | Yes |
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.
| Type | string |
| Required | No |
variables
Key-value pairs used to interpolate {{name}} placeholders in strings throughout the movie. Variable names are restricted to letters, numbers, and underscores; names starting with ?, $, @, %, &, or _ are reserved.
| Type | object |
| Required | No |
| Default Value | {} |
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.
| Type | integer |
| Required | No |
| Default Value | 640 |
| Minimum Value | 50 |
| Maximum Value | 3840 |
draft
Deprecated. Ignored by the renderer; watermarking is now controlled automatically by the account plan.
| Type | boolean |
| Required | No |
| Deprecated | Yes |