JSON Structure Overview

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

{
  "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

interface Project {
  name?: string;
  width?: number;
  height?: number;
  resolution?: ResolutionPreset;
  duration?: number;
  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.
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.

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:

• PositionPreset
• Anchor
• ResizeMode
• zoom
• FilterOptions
• CropParams
• ChromaKey
• BorderRadius
• XFadeEffect
• Caption
• Word
• SubtitleStyles

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: inline SVG only — deprecated; embed SVG inside an HTML element instead.

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

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