Skip to main content

Image Elements

IMAGE elements add remote raster images to the composition. The API validates the URL and visual options, then Zvid downloads and checks the asset before rendering.

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​

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"
}
resize: cover on a 960×540 canvas

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
  }
}
cropParams keeps a 800×600 window of the source

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": "30",
    "blur": "2"
  }
}
Rounded corners with radius