VideoCascadeLogo
VideoCascade

GIF Overlays

Add animated GIF overlays, stickers, and reactions to your videos

GIF elements allow you to overlay animated GIFs on your videos. Perfect for animated stickers, reactions, decorative elements, and any visual effect that requires simple animation.

GIF Element Structure

interface GifElement {
  type: 'gif';
  url: string;
  timing: TimingConfig;
  position: PositionConfig;
  size: SizeConfig;
  effects?: VisualEffects;
  zIndex?: number;
  loop?: boolean;
}

Required Properties

PropertyTypeDescription
type'gif'Must be "gif"
urlstringURL to the GIF file (must be publicly accessible)
timingTimingConfigWhen to show the GIF
positionPositionConfigWhere to place the GIF
sizeSizeConfigSize of the GIF overlay

Optional Properties

PropertyTypeDefaultDescription
effectsVisualEffectsundefinedVisual effects like opacity and fades
zIndexnumber0Stacking order (higher = on top)
loopbooleantrueWhether to loop the GIF animation

GIFs vs Images: GIF elements work exactly like image elements but with animation support and a loop property. All position, size, timing, and effects options work the same way.

Loop Property

The loop property controls whether the GIF animation repeats:

Loop Enabled (Default)

The GIF will continuously loop while visible:

{
  "type": "gif",
  "url": "https://example.com/celebration.gif",
  "loop": true
}

Use cases:

  • Background decorations
  • Continuous reactions
  • Loading indicators
  • Ambient effects

Loop Disabled

The GIF plays once and stops on the last frame:

{
  "type": "gif",
  "url": "https://example.com/one-time-effect.gif",
  "loop": false
}

Use cases:

  • One-time reactions
  • Entrance animations
  • Transition effects
  • Reveal animations

Timing Consideration: When loop: false, ensure your timing duration matches or exceeds the GIF's animation duration, or the GIF may freeze before your timing ends.

Animated GIF Support

VideoCascadefully supports animated GIFs with multiple frames:

  • Frame rate preservation: Original GIF timing is maintained
  • Transparency support: Transparent GIFs work perfectly
  • Any frame count: From simple 2-frame animations to complex multi-frame GIFs
  • Variable frame delays: Each frame can have different timing

Complete Examples

Animated Reaction Sticker

Add a celebration GIF at a specific moment:

curl -X POST https://api.videocascade.com/v1/videos \
  -H "Authorization: Bearer vca_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUrl": "https://example.com/video.mp4",
    "elements": [
      {
        "type": "gif",
        "url": "https://example.com/celebration.gif",
        "timing": {
          "startTime": 30,
          "endTime": 35
        },
        "position": { "anchor": "top-right" },
        "size": { "width": "25%" },
        "effects": {
          "fadeIn": { "duration": 0.3 },
          "fadeOut": { "duration": 0.3 }
        },
        "loop": true,
        "zIndex": 50
      }
    ]
  }'
const response = await fetch('https://api.videocascade.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vca_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fileUrl: 'https://example.com/video.mp4',
    elements: [
      {
        type: 'gif',
        url: 'https://example.com/celebration.gif',
        timing: {
          startTime: 30,
          endTime: 35,
        },
        position: { anchor: 'top-right' },
        size: { width: '25%' },
        effects: {
          fadeIn: { duration: 0.3 },
          fadeOut: { duration: 0.3 },
        },
        loop: true,
        zIndex: 50,
      },
    ],
  }),
});

const data = await response.json();
console.log('Video ID:', data.videoId);
import requests

response = requests.post(
    'https://api.videocascade.com/v1/videos',
    headers={
        'Authorization': 'Bearer vca_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'fileUrl': 'https://example.com/video.mp4',
        'elements': [
            {
                'type': 'gif',
                'url': 'https://example.com/celebration.gif',
                'timing': {
                    'startTime': 30,
                    'endTime': 35,
                },
                'position': {'anchor': 'top-right'},
                'size': {'width': '25%'},
                'effects': {
                    'fadeIn': {'duration': 0.3},
                    'fadeOut': {'duration': 0.3},
                },
                'loop': True,
                'zIndex': 50,
            },
        ],
    }
)

data = response.json()
print(f"Video ID: {data['videoId']}")
interface GifElement {
  type: 'gif';
  url: string;
  timing: {
    startTime: number;
    endTime: number;
  };
  position: { anchor: string };
  size: { width: string };
  effects?: {
    fadeIn?: { duration: number };
    fadeOut?: { duration: number };
  };
  loop: boolean;
  zIndex: number;
}

const celebrationGif: GifElement = {
type: 'gif',
url: 'https://example.com/celebration.gif',
timing: {
startTime: 30,
endTime: 35,
},
position: { anchor: 'top-right' },
size: { width: '25%' },
effects: {
fadeIn: { duration: 0.3 },
fadeOut: { duration: 0.3 },
},
loop: true,
zIndex: 50,
};

const response = await fetch('https://api.videocascade.com/v1/videos', {
method: 'POST',
headers: {
'Authorization': 'Bearer vca_your_api_key',
'Content-Type': 'application/json',
},
body: JSON.stringify({
fileUrl: 'https://example.com/video.mp4',
elements: [celebrationGif],
}),
});

Corner Decoration

Add a looping animated corner decoration:

{
  "type": "gif",
  "url": "https://example.com/sparkle.gif",
  "timing": { "entireVideo": true },
  "position": { "anchor": "top-left" },
  "size": { "width": "15%" },
  "effects": { "opacity": 0.8 },
  "loop": true,
  "zIndex": 20
}

One-Time Transition Effect

Add a transition effect that plays once:

{
  "type": "gif",
  "url": "https://example.com/transition-wipe.gif",
  "timing": {
    "startTime": 15,
    "endTime": 17
  },
  "position": { "anchor": "center" },
  "size": { "width": "100%" },
  "loop": false,
  "zIndex": 100
}

Multiple Animated Stickers

Add multiple GIFs at different times:

{
  "fileUrl": "https://example.com/video.mp4",
  "elements": [
    {
      "type": "gif",
      "url": "https://example.com/thumbs-up.gif",
      "timing": { "startTime": 10, "endTime": 13 },
      "position": { "anchor": "bottom-left" },
      "size": { "width": "20%" },
      "loop": true,
      "zIndex": 30
    },
    {
      "type": "gif",
      "url": "https://example.com/heart-eyes.gif",
      "timing": { "startTime": 25, "endTime": 28 },
      "position": { "anchor": "bottom-right" },
      "size": { "width": "20%" },
      "loop": true,
      "zIndex": 30
    },
    {
      "type": "gif",
      "url": "https://example.com/fire.gif",
      "timing": { "startTime": 40, "endTime": 43 },
      "position": { "x": "50%", "y": "30%" },
      "size": { "width": "25%" },
      "loop": true,
      "zIndex": 30
    }
  ]
}

Common Use Cases

Social Media Reactions

Add animated emoji reactions:

{
  "type": "gif",
  "url": "https://cdn.example.com/reactions/laughing-emoji.gif",
  "timing": { "startTime": 5, "endTime": 8 },
  "position": { "anchor": "center" },
  "size": { "width": "30%" },
  "effects": {
    "fadeIn": { "duration": 0.2 },
    "fadeOut": { "duration": 0.2 }
  },
  "loop": true,
  "zIndex": 60
}

Use an animated version of your logo:

{
  "type": "gif",
  "url": "https://cdn.example.com/animated-logo.gif",
  "timing": { "startTime": 0, "endTime": 3 },
  "position": { "anchor": "center" },
  "size": { "width": "40%" },
  "effects": {
    "fadeOut": { "duration": 0.5, "easing": "ease-out" }
  },
  "loop": false,
  "zIndex": 100
}

Loading Indicator

Add a loading spinner overlay:

{
  "type": "gif",
  "url": "https://cdn.example.com/loading-spinner.gif",
  "timing": { "startTime": 20, "endTime": 25 },
  "position": { "anchor": "center" },
  "size": { "width": "10%" },
  "loop": true,
  "zIndex": 80
}

Decorative Elements

Add animated decorative elements:

{
  "type": "gif",
  "url": "https://cdn.example.com/sparkles.gif",
  "timing": { "entireVideo": true },
  "position": { "x": "90%", "y": "10%" },
  "size": { "width": "12%" },
  "effects": { "opacity": 0.6 },
  "loop": true,
  "zIndex": 5
}

Pop-up Notification Style

Add a notification-style GIF:

{
  "type": "gif",
  "url": "https://cdn.example.com/notification-popup.gif",
  "timing": { "startTime": 15, "endTime": 18 },
  "position": { "anchor": "top-center" },
  "size": { "width": "50%" },
  "effects": {
    "fadeIn": { "duration": 0.3, "easing": "ease-out" }
  },
  "loop": false,
  "zIndex": 90
}

Animated Sticker Pack

Create an animated sticker pack effect:

{
  "fileUrl": "https://example.com/video.mp4",
  "elements": [
    {
      "type": "gif",
      "url": "https://cdn.example.com/stickers/party-hat.gif",
      "timing": { "entireVideo": true },
      "position": { "x": "15%", "y": "15%" },
      "size": { "width": "12%" },
      "loop": true,
      "zIndex": 40
    },
    {
      "type": "gif",
      "url": "https://cdn.example.com/stickers/confetti.gif",
      "timing": { "entireVideo": true },
      "position": { "x": "85%", "y": "15%" },
      "size": { "width": "12%" },
      "loop": true,
      "zIndex": 40
    },
    {
      "type": "gif",
      "url": "https://cdn.example.com/stickers/balloons.gif",
      "timing": { "entireVideo": true },
      "position": { "x": "50%", "y": "10%" },
      "size": { "width": "15%" },
      "loop": true,
      "zIndex": 40
    }
  ]
}

Advanced Examples

Sequenced GIF Reactions

Create a sequence of reactions:

{
  "fileUrl": "https://example.com/video.mp4",
  "elements": [
    {
      "type": "gif",
      "url": "https://cdn.example.com/reaction-1.gif",
      "timing": { "startTime": 5, "endTime": 7 },
      "position": { "anchor": "bottom-left" },
      "size": { "width": "20%" },
      "effects": {
        "fadeIn": { "duration": 0.2 },
        "fadeOut": { "duration": 0.2 }
      },
      "loop": true,
      "zIndex": 50
    },
    {
      "type": "gif",
      "url": "https://cdn.example.com/reaction-2.gif",
      "timing": { "startTime": 12, "endTime": 14 },
      "position": { "anchor": "bottom-left" },
      "size": { "width": "20%" },
      "effects": {
        "fadeIn": { "duration": 0.2 },
        "fadeOut": { "duration": 0.2 }
      },
      "loop": true,
      "zIndex": 50
    },
    {
      "type": "gif",
      "url": "https://cdn.example.com/reaction-3.gif",
      "timing": { "startTime": 20, "endTime": 22 },
      "position": { "anchor": "bottom-left" },
      "size": { "width": "20%" },
      "effects": {
        "fadeIn": { "duration": 0.2 },
        "fadeOut": { "duration": 0.2 }
      },
      "loop": true,
      "zIndex": 50
    }
  ]
}

Layered Animation Effects

Layer multiple GIFs for complex effects:

{
  "elements": [
    {
      "type": "gif",
      "url": "https://cdn.example.com/background-animation.gif",
      "timing": { "startTime": 10, "endTime": 20 },
      "position": { "anchor": "center" },
      "size": { "width": "100%" },
      "effects": { "opacity": 0.3 },
      "loop": true,
      "zIndex": 1
    },
    {
      "type": "gif",
      "url": "https://cdn.example.com/foreground-animation.gif",
      "timing": { "startTime": 10, "endTime": 20 },
      "position": { "anchor": "center" },
      "size": { "width": "60%" },
      "loop": true,
      "zIndex": 50
    },
    {
      "type": "gif",
      "url": "https://cdn.example.com/particle-effect.gif",
      "timing": { "startTime": 10, "endTime": 20 },
      "position": { "anchor": "center" },
      "size": { "width": "100%" },
      "effects": { "opacity": 0.5 },
      "loop": true,
      "zIndex": 100
    }
  ]
}

GIF with Precise Positioning

Position multiple GIFs in a grid:

{
  "elements": [
    {
      "type": "gif",
      "url": "https://cdn.example.com/corner-1.gif",
      "timing": { "entireVideo": true },
      "position": { "x": "5%", "y": "5%" },
      "size": { "width": "10%" },
      "loop": true,
      "zIndex": 20
    },
    {
      "type": "gif",
      "url": "https://cdn.example.com/corner-2.gif",
      "timing": { "entireVideo": true },
      "position": { "x": "95%", "y": "5%" },
      "size": { "width": "10%" },
      "loop": true,
      "zIndex": 20
    },
    {
      "type": "gif",
      "url": "https://cdn.example.com/corner-3.gif",
      "timing": { "entireVideo": true },
      "position": { "x": "5%", "y": "95%" },
      "size": { "width": "10%" },
      "loop": true,
      "zIndex": 20
    },
    {
      "type": "gif",
      "url": "https://cdn.example.com/corner-4.gif",
      "timing": { "entireVideo": true },
      "position": { "x": "95%", "y": "95%" },
      "size": { "width": "10%" },
      "loop": true,
      "zIndex": 20
    }
  ]
}

Best Practices

GIF Optimization

Optimize your GIFs to reduce file size and processing time: - Limit color palette (fewer colors = smaller file) - Reduce frame count when possible - Optimize frame delays - Compress with tools like Gifsicle or ezGIF - Consider resolution (don't use huge GIFs for small overlays)

Loop Considerations

When to loop:

  • Continuous ambient effects
  • Background decorations
  • Repeating patterns
  • Long display durations

When not to loop:

  • One-time reactions
  • Transition effects
  • Reveal animations
  • Short display durations (< 2 seconds)

Timing Best Practices

Match content:

{
  "timing": { "startTime": 10, "endTime": 13 }
}

Show reactions at relevant moments in your video.

Use fade transitions:

{
  "effects": {
    "fadeIn": { "duration": 0.3 },
    "fadeOut": { "duration": 0.3 }
  }
}

Smooth transitions look more professional.

Consider GIF duration:

  • Short GIFs (< 1s): Use longer timing with loop
  • Long GIFs (> 3s): Consider loop: false or match timing to GIF duration

Size Guidelines

For stickers and reactions:

  • Size: 15-30% of video width
  • Position: Corners or sides
  • Loop: true (usually)

For decorative elements:

  • Size: 10-20% of video width
  • Position: Corners with safe margins
  • Opacity: 0.5-0.8 for subtlety

For full-screen effects:

  • Size: 80-100% of video width
  • Position: center
  • Opacity: 0.2-0.4 to not overwhelm

Performance Tips

File size matters:

  • Keep GIFs under 2MB when possible
  • Use fewer frames for background elements
  • Optimize color palettes
  • Reduce dimensions for small overlays

Limit GIF count:

  • Don't use too many GIFs simultaneously
  • Each GIF adds processing overhead
  • Consider using static images when animation isn't needed

Visual Quality

Transparency:

  • Use GIFs with transparent backgrounds for overlays
  • Solid backgrounds may block video content

Resolution:

  • Use high-quality source GIFs
  • Don't upscale low-resolution GIFs
  • Match GIF quality to final video quality

Color:

  • Ensure GIFs match your brand colors
  • Consider video color palette
  • Test GIF visibility on different backgrounds

Troubleshooting

GIF Not Animating

Possible causes:

  1. GIF is actually a static image
  2. Loop is set to false and animation finished
  3. Only one frame in the GIF
  4. Timing duration too short

Solutions:

  • Verify GIF is actually animated (test in browser)
  • Set loop: true for continuous animation
  • Extend timing duration
  • Check GIF frame count

GIF Appears Static or Frozen

Possible causes:

  1. Loop is disabled
  2. Timing doesn't cover full GIF duration
  3. GIF failed to load

Solutions:

{
  "loop": true,
  "timing": { "entireVideo": true }
}

Performance Issues

Symptoms:

  • Slow processing
  • Large output file
  • Choppy playback

Solutions:

  • Reduce GIF file size
  • Use fewer GIFs simultaneously
  • Optimize GIF frame rate
  • Reduce GIF dimensions

GIF Quality Poor

Solutions:

  • Use higher quality source GIF
  • Don't upscale small GIFs
  • Ensure proper color depth
  • Check compression settings

GIF vs Static Image

Use GIFs when:

  • Animation adds value
  • You need attention-grabbing effects
  • Creating reactions or emotive elements
  • Adding decorative animations

Use static images when:

  • Animation isn't necessary
  • File size is a concern
  • Processing speed is priority
  • You need sharper quality

Finding GIF Resources

Popular GIF sources:

  • GIPHY - Large library of GIFs and stickers
  • Tenor - GIF keyboard and API
  • Custom creation - Tools like After Effects, Photoshop
  • Screen recordings - Convert videos to GIFs

CDN Hosting: Host your GIFs on a fast CDN for best performance. Ensure URLs are publicly accessible.

Next Steps

Image Overlays

Learn about static image overlays

Video Overlays

Add video overlays and picture-in-picture

Audio Overlays

Add background music and sound effects

Overlay Examples

See complete overlay examples

Image Overlays

Add static image overlays, watermarks, and logos to your videos

Video Overlays

Add picture-in-picture, B-roll, and video element overlays to your videos

On this page

GIF Element StructureRequired PropertiesOptional PropertiesLoop PropertyLoop Enabled (Default)Loop DisabledAnimated GIF SupportComplete ExamplesAnimated Reaction StickerCorner DecorationOne-Time Transition EffectMultiple Animated StickersCommon Use CasesSocial Media ReactionsAnimated LogoLoading IndicatorDecorative ElementsPop-up Notification StyleAnimated Sticker PackAdvanced ExamplesSequenced GIF ReactionsLayered Animation EffectsGIF with Precise PositioningBest PracticesGIF OptimizationLoop ConsiderationsTiming Best PracticesSize GuidelinesPerformance TipsVisual QualityTroubleshootingGIF Not AnimatingGIF Appears Static or FrozenPerformance IssuesGIF Quality PoorGIF vs Static ImageFinding GIF ResourcesNext Steps