Skip to main content

Image Elements

IMAGE elements add remote images to the composition. The API validates the URL and visual options, then Zvid downloads and checks the asset before rendering. Use a public direct media URL; see Media assets for uploads, supported sources, and download failures.

Interface​

interface ImageItem {
  type: "IMAGE";
  src: string;
  x?: number;
  y?: number;
  width?: number;
  height?: number;
  anchor?: Anchor;
  position?: PositionPreset;
  resize?: "contain" | "cover";
  enterBegin?: number;
  enterEnd?: number;
  exitBegin?: number;
  exitEnd?: number;
  track?: number;
  opacity?: number;
  angle?: number;
  flipV?: boolean;
  flipH?: boolean;
  enterAnimation?: XFadeEffect | null;
  exitAnimation?: XFadeEffect | null;
  filter?: FilterOptions;
  cropParams?: CropParams;
  chromaKey?: ChromaKey;
  radius?: BorderRadius;
  zoom?: boolean | { depth?: number };
}

Required Fields​

PropertyTypeNotes
type"IMAGE"Case-insensitive in API validation.
srcstringRemote http or https URL.

Properties​

Placement, timing, layering, and animation fields are shared by all visual elements — see Common Element Properties. Images support every media option in the support matrix: resize, zoom, filter, cropParams, chromaKey, and radius.

Examples​

The JSON blocks are visual element fragments for payload.visuals or a scene's visuals. The recorded previews demonstrate the named property with their own full project fixtures, available alongside each preview. Their canvas sizes and surrounding composition can differ from the short fragments.

Simple Image​

{
  "type": "IMAGE",
  "src": "https://cdn.pixabay.com/photo/2022/08/16/05/50/straw-bales-7389396_1280.jpg",
  "x": 100,
  "y": 100,
  "width": 400,
  "height": 300
}

Centered Cover Image​

{
  "type": "IMAGE",
  "src": "https://cdn.pixabay.com/photo/2024/10/02/18/24/leaf-9091894_1280.jpg",
  "width": 1280,
  "height": 720,
  "position": "center-center",
  "resize": "cover"
}
{
  "name": "docs-img-cover",
  "width": 960,
  "height": 540,
  "duration": 4,
  "backgroundColor": "#000000",
  "visuals": [
    {
      "type": "IMAGE",
      "src": "https://cdn.pixabay.com/photo/2024/10/02/18/24/leaf-9091894_1280.jpg",
      "width": 960,
      "height": 540,
      "position": "center-center",
      "resize": "cover"
    }
  ]
}
Rendered by Zvid
Recorded fixture: resize cover on a 960×540 canvas
Watch video

Cropped Image​

{
  "type": "IMAGE",
  "src": "https://cdn.pixabay.com/photo/2023/06/04/20/21/cat-8040862_1280.jpg",
  "x": 300,
  "y": 200,
  "width": 400,
  "height": 300,
  "cropParams": {
    "x": 100,
    "y": 50,
    "width": 800,
    "height": 600
  }
}
{
  "name": "docs-img-crop",
  "width": 960,
  "height": 540,
  "duration": 4,
  "backgroundColor": "#1e1b31",
  "visuals": [
    {
      "type": "IMAGE",
      "src": "https://cdn.pixabay.com/photo/2023/06/04/20/21/cat-8040862_1280.jpg",
      "x": 280,
      "y": 120,
      "width": 400,
      "height": 300,
      "cropParams": {
        "x": 100,
        "y": 50,
        "width": 800,
        "height": 600
      }
    }
  ]
}
Rendered by Zvid
Recorded fixture: a cropped source image
Watch video

Rounded Corners And Filters​

{
  "type": "IMAGE",
  "src": "https://cdn.pixabay.com/photo/2022/11/05/22/11/channel-7572879_1280.jpg",
  "width": 300,
  "height": 200,
  "position": "bottom-right",
  "radius": {
    "tl": 10,
    "tr": 10,
    "bl": 10,
    "br": 10
  },
  "filter": {
    "brightness": -10,
    "hue-rotate": "30deg",
    "blur": 20
  }
}
{
  "name": "docs-img-radius",
  "width": 960,
  "height": 540,
  "duration": 4,
  "backgroundColor": "#1e1b31",
  "visuals": [
    {
      "type": "IMAGE",
      "src": "https://cdn.pixabay.com/photo/2022/11/05/22/11/channel-7572879_1280.jpg",
      "width": 480,
      "height": 320,
      "position": "center-center",
      "radius": {
        "tl": 32,
        "tr": 32,
        "bl": 32,
        "br": 32
      }
    }
  ]
}
Rendered by Zvid
Recorded fixture: 32-pixel rounded corners, without the fragment's filters
Watch video