JSON Structure Overview

A Zvid project is a plain JSON object submitted as payload to POST /api/render/api-key.

The outer request envelope contains payload or a stored template ID, plus optional request variables and output overrides. The project is the object inside payload; an element belongs in its visuals array (or a scene's visuals). Audio belongs in audios. Do not nest a second payload inside a project exported by the editor.

{
  "payload": {
    "name": "my-video",
    "duration": 30,
    "visuals": [],
    "audios": []
  }
}

The Zvid API validates the payload, checks account limits, queues the render, resolves remote assets, and produces the final video.

Project Object

The interface below describes resolved video projects. Image projects share layout fields but have a different set of allowed fields; see Rendering images. Authoring-time variables, condition, and scene iterate are resolved before this shape is validated; see Templates.

For video projects, durationMode: "auto" derives length from the scene sequence (minus transition overlaps), timed global elements, audio and captions. In this mode duration is an optional minimum. Without timed content or a minimum, the fallback is 10 seconds. Omit durationMode or use "fixed" to retain legacy timing. A scene project always includes its full scene sequence, including when a shorter root duration is supplied.

For API submission in Auto mode, videos need exitEnd or videoEnd, and audio needs exit, audioEnd, or matchDuration: true. This lets the API validate the complete length against your plan before reserving credits. The editor resolves media lengths before submitting a render. The standalone renderer can also probe source lengths. Both timing fields are video-only.

interface Project {
  name?: string;
  width?: number;
  height?: number;
  resolution?: ResolutionPreset;
  duration?: number;
  durationMode?: "auto" | "fixed";
  frameRate?: number;
  backgroundColor?: string;
  outputFormat?: "mp4" | "mov" | "avi" | "webm";
  visuals?: Item[];
  audios?: AudioItem[];
  scenes?: Scene[];
  thumbnail?: string;
  subtitle?: Subtitle;
}

Property	Type	Required	Default	Notes
`name`	`string`	No	`"unnamed"`	Output filename without extension. Letters, numbers, spaces, `_`, and `-` are accepted by API validation.
`width`	`number`	No	`1280`	Used for custom resolution. Limited by the user's plan.
`height`	`number`	No	`720`	Used for custom resolution. Limited by the user's plan.
`resolution`	`ResolutionPreset`	No	custom dimensions	Preset dimensions override `width` and `height` when not `custom`.
`duration`	`number`	No	`10`	Seconds. Minimum `0.1`; maximum is plan-dependent.
`durationMode`	`"auto" \| "fixed"`	No	fixed behavior when omitted	Video only. Auto derives output length; `duration` becomes a minimum. See Timing.
`frameRate`	`number`	No	`30`	Integer from `1` to `60`.
`backgroundColor`	`string`	No	`#ffffff`	Hex color, such as `#000000`.
`outputFormat`	`string`	No	`mp4`	API accepts only `mp4`, `mov`, `avi`, and `webm`.
`visuals`	`Item[]`	No	`[]`	Text/HTML, image, video, GIF, and (deprecated) SVG elements. When `scenes` is set, these act as a global overlay layer.
`audios`	`AudioItem[]`	No	`[]`	External audio tracks.
`scenes`	`Scene[]`	No	none	Sequential, self-contained segments. When present, drives the timeline; `visuals`/`audios` overlay all scenes.
`thumbnail`	`string`	No	generated when absent	Optional remote image URL.
`subtitle`	`Subtitle`	No	none	Caption and subtitle configuration.

type selects "video" (default) or "image". Image-only fields are snapshotTime, quality, and transparent; image formats and forbidden video fields are documented in Rendering images. Project and scene variables hold authoring defaults, not rendered content.

Resolution Presets

See the ResolutionPreset source reference for supported preset names, dimensions, and usage notes.

Property Reference

All visual elements share timeline, transform, and layering fields — see Common Element Properties for the canonical tables and the media-support matrix. The pages below are the source references for reusable typed properties:

Element Types

Text & HTML Elements: plain text or HTML with native CSS and JavaScript.
Image Elements: remote image sources, filters, crop, radius, chroma key, resize, and zoom.
Video Elements: remote video clips, trim timing, audio, playback speed, transitions, resize, and zoom.
GIF Elements: animated GIFs with timing, resize, zoom, crop, filters, and chroma key.
SVG Elements: deprecated — use HTML elements instead.
Audio Elements: background music, narration, and sound effects.
Subtitle: word-timed captions and subtitle styling.
Animation Effects: enter and exit animations for visual elements.
Video Transitions: video-to-video xfade transitions.

Scenes

For multi-part videos, use Scenes. The scenes array splits a project into sequential, self-contained segments, each with its own local timeline and optional cross-scene transition. Project-level visuals and audios then render as a global overlay spanning every scene.

Defaults

Project Defaults

Property	Default
`width`	`1280`
`height`	`720`
`duration`	`10`
`frameRate`	`30`
`backgroundColor`	`#ffffff`
`outputFormat`	`mp4`
`name`	`unnamed`
`visuals`	`[]`
`audios`	`[]`

Visual Defaults

Shared visual defaults (position, timing, opacity, track, animations) are listed in Common Element Properties.

Video Defaults

Property	Default
`videoBegin`	`0`
`videoEnd`	project duration or source duration when available
`videoDuration`	project duration or source duration when available
`volume`	`1`
`speed`	`1`
`transition`, `transitionId`	`null`

Audio Defaults

Property	Default
`enter`	`0`
`exit`	project duration
`audioBegin`	`0`
`audioEnd`	project duration or source duration when available
`audioDuration`	project duration or source duration when available
`volume`	`1`
`speed`	`1`

Supported Formats

Input media: remote HTTP/HTTPS assets accepted by API validation and checked during rendering.
Output video: mp4, mov, avi, or webm.
HTML: HTML markup with native CSS and JavaScript via customCode, described in Text & HTML Elements.
SVG: the legacy SVG element accepts safe inline markup. For new HTML layouts, use the restricted geometry-only SVG subset described in Text & HTML Elements.

Resource Limits

Limits are plan-dependent and enforced before or during rendering. They include output resolution, project duration, input media resolution, media size, and element counts by type. Validation errors include the active plan limits when the payload exceeds them.

Quick Examples

These are element fragments, not complete render requests. Put visual fragments in payload.visuals and audio fragments in payload.audios. Use Quick Start for a complete request, and run free validation before rendering.

Basic Text Element

{
  "type": "TEXT",
  "text": "Hello World",
  "x": 640,
  "y": 360,
  "anchor": "center-center",
  "style": {
    "fontSize": 48,
    "color": "#000000",
    "textAlign": "center"
  }
}

Basic Image Element

{
  "type": "IMAGE",
  "src": "https://images.pexels.com/photos/32972375/pexels-photo-32972375.jpeg",
  "x": 100,
  "y": 100,
  "width": 607,
  "height": 910
}

Basic Video Element

{
  "type": "VIDEO",
  "src": "https://videos.pexels.com/video-files/1409899/1409899-sd_640_360_25fps.mp4",
  "videoEnd": 10,
  "volume": 0
}

Basic Audio Element

{
  "src": "https://cdn.pixabay.com/audio/2025/04/21/audio_ed6f0ed574.mp3",
  "volume": 0.5
}

Next Steps

Quick Start
Common Element Properties
Examples
FAQ
Timing — projects, scenes, source trims, and automatic length
Layout — pixels, boxes, positioning, and anchors
Documentation resources — schemas and machine-readable references

Project Object​

Resolution Presets​

Property Reference​

Element Types​

Scenes​

Defaults​

Project Defaults​

Visual Defaults​

Video Defaults​

Audio Defaults​

Supported Formats​

Resource Limits​

Quick Examples​

Basic Text Element​

Basic Image Element​

Basic Video Element​

Basic Audio Element​

Next Steps​