--- title: "JSON Structure Overview" canonical_url: https://docs.zvid.io/docs/structure/ source: docs/structure.md content_revision: 6338386a1dd87e4a --- # 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. ```json { "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](https://docs.zvid.io/docs/rendering-images/). Authoring-time `variables`, `condition`, and scene `iterate` are resolved before this shape is validated; see [Templates](https://docs.zvid.io/docs/templates/template-basics/). 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. ```typescript 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`](https://docs.zvid.io/docs/structure/properties/resolution-presets/) | 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](https://docs.zvid.io/docs/concepts/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[]`](https://docs.zvid.io/docs/structure/scenes/) | 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](https://docs.zvid.io/docs/rendering-images/). Project and scene `variables` hold authoring defaults, not rendered content. ## Resolution Presets See the [`ResolutionPreset`](https://docs.zvid.io/docs/structure/properties/resolution-presets/) 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](https://docs.zvid.io/docs/structure/common-properties/) for the canonical tables and the media-support matrix. The pages below are the source references for reusable typed properties: - [`PositionPreset`](https://docs.zvid.io/docs/structure/properties/position/) - [`Anchor`](https://docs.zvid.io/docs/structure/properties/anchor/) - [`ResizeMode`](https://docs.zvid.io/docs/structure/properties/resize/) - [`zoom`](https://docs.zvid.io/docs/structure/properties/zoom/) - [`FilterOptions`](https://docs.zvid.io/docs/structure/properties/filter-options/) - [`CropParams`](https://docs.zvid.io/docs/structure/properties/crop-params/) - [`ChromaKey`](https://docs.zvid.io/docs/structure/properties/chroma-key/) - [`BorderRadius`](https://docs.zvid.io/docs/structure/properties/border-radius/) - [`XFadeEffect`](https://docs.zvid.io/docs/structure/properties/xfade-effects/) - [`Caption`](https://docs.zvid.io/docs/structure/properties/caption/) - [`Word`](https://docs.zvid.io/docs/structure/properties/word/) - [`SubtitleStyles`](https://docs.zvid.io/docs/structure/properties/subtitle-styles/) ## Element Types - [Text & HTML Elements](https://docs.zvid.io/docs/structure/text-elements/): plain text or HTML with native CSS and JavaScript. - [Image Elements](https://docs.zvid.io/docs/structure/image-elements/): remote image sources, filters, crop, radius, chroma key, resize, and zoom. - [Video Elements](https://docs.zvid.io/docs/structure/video-elements/): remote video clips, trim timing, audio, playback speed, transitions, resize, and zoom. - [GIF Elements](https://docs.zvid.io/docs/structure/gif-elements/): animated GIFs with timing, resize, zoom, crop, filters, and chroma key. - [SVG Elements](https://docs.zvid.io/docs/structure/svg-elements/): **deprecated** — use [HTML elements](https://docs.zvid.io/docs/structure/text-elements/) instead. - [Audio Elements](https://docs.zvid.io/docs/structure/audio-elements/): background music, narration, and sound effects. - [Subtitle](https://docs.zvid.io/docs/structure/subtitle/): word-timed captions and subtitle styling. - [Animation Effects](https://docs.zvid.io/docs/structure/animations/): enter and exit animations for visual elements. - [Video Transitions](https://docs.zvid.io/docs/structure/transitions/): video-to-video xfade transitions. ## Scenes For multi-part videos, use [Scenes](https://docs.zvid.io/docs/structure/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](https://docs.zvid.io/docs/structure/common-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](https://docs.zvid.io/docs/structure/text-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](https://docs.zvid.io/docs/structure/text-elements/#inline-svg-in-html). ## 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](https://docs.zvid.io/docs/quick-start/) for a complete request, and run [free validation](https://docs.zvid.io/docs/validate-and-estimate/) before rendering. ### Basic Text Element ```json { "type": "TEXT", "text": "Hello World", "x": 640, "y": 360, "anchor": "center-center", "style": { "fontSize": 48, "color": "#000000", "textAlign": "center" } } ``` ### Basic Image Element ```json { "type": "IMAGE", "src": "https://images.pexels.com/photos/32972375/pexels-photo-32972375.jpeg", "x": 100, "y": 100, "width": 607, "height": 910 } ``` ### Basic Video Element ```json { "type": "VIDEO", "src": "https://videos.pexels.com/video-files/1409899/1409899-sd_640_360_25fps.mp4", "videoEnd": 10, "volume": 0 } ``` ### Basic Audio Element ```json { "src": "https://cdn.pixabay.com/audio/2025/04/21/audio_ed6f0ed574.mp3", "volume": 0.5 } ``` ## Next Steps - [Quick Start](https://docs.zvid.io/docs/quick-start/) - [Common Element Properties](https://docs.zvid.io/docs/structure/common-properties/) - [Examples](https://docs.zvid.io/docs/examples/inspirational-video/) - [FAQ](https://docs.zvid.io/docs/faq/) - [Timing](https://docs.zvid.io/docs/concepts/timing/) — projects, scenes, source trims, and automatic length - [Layout](https://docs.zvid.io/docs/concepts/layout/) — pixels, boxes, positioning, and anchors - [Documentation resources](https://docs.zvid.io/docs/documentation-resources/) — schemas and machine-readable references