Skip to main content

GIF Elements

GIF elements add animated GIF assets to a project. The hosted API accepts GIFs as media-like visual elements, including timing, transform, resize, zoom, crop, filters, and chroma key options.

Interface​

interface GIFItem {
  type: "GIF";
  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;
  zoom?: boolean | { depth?: number };
  radius?: BorderRadius;
}

Required Fields​

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

Properties​

GIF elements behave like images: they share the common element properties and support every media option in the support matrix — resize, zoom, filter, cropParams, chromaKey, and radius. The GIF's own animation loops for the element's visible duration.

Examples​

These are visual element fragments for a video project's payload.visuals. GIF elements are rejected in image projects; use a static image instead. The recorded preview includes a background and its own GIF placement; use its full payload for that exact composition.

Simple GIF​

{
  "type": "GIF",
  "src": "https://media.giphy.com/media/3oEjI6SIIHBdRxXI40/giphy.gif",
  "position": "center-center",
  "track": 10
}
{
  "name": "docs-gif-overlay",
  "width": 960,
  "height": 540,
  "duration": 5,
  "backgroundColor": "#000000",
  "visuals": [
    {
      "type": "VIDEO",
      "src": "https://cdn.pixabay.com/video/2025/06/09/284566_large.mp4",
      "resize": "cover",
      "width": 960,
      "height": 540,
      "volume": 0
    },
    {
      "type": "GIF",
      "src": "https://media.giphy.com/media/3oEjI6SIIHBdRxXI40/giphy.gif",
      "width": 260,
      "height": 260,
      "resize": "contain",
      "position": "bottom-left",
      "track": 10
    }
  ]
}
Rendered by Zvid
Recorded fixture: a GIF over a video background
Watch video

Resized GIF​

{
  "type": "GIF",
  "src": "https://media.giphy.com/media/3oEjI6SIIHBdRxXI40/giphy.gif",
  "width": 300,
  "height": 300,
  "resize": "contain",
  "position": "bottom-right",
  "opacity": 0.8
}

Cropped GIF​

{
  "type": "GIF",
  "src": "https://media.giphy.com/media/3oEjI6SIIHBdRxXI40/giphy.gif",
  "width": 300,
  "height": 200,
  "cropParams": {
    "x": 50,
    "y": 25,
    "width": 400,
    "height": 300
  }
}