Image Overlays

Image elements allow you to overlay static images on your videos. Perfect for watermarks, logos, branding, lower thirds, and any visual element that doesn't need animation.

Image Element Structure

interface ImageElement {
  type: 'image';
  url: string;
  timing: TimingConfig;
  position: PositionConfig;
  size: SizeConfig;
  effects?: VisualEffects;
  zIndex?: number;
}

Required Properties

Property	Type	Description
`type`	`'image'`	Must be `"image"`
`url`	`string`	URL to the image file (must be publicly accessible)
`timing`	`TimingConfig`	When to show the image
`position`	`PositionConfig`	Where to place the image
`size`	`SizeConfig`	Size of the image overlay

Optional Properties

Property	Type	Default	Description
`effects`	`VisualEffects`	`undefined`	Visual effects like opacity and fades
`zIndex`	`number`	`0`	Stacking order (higher = on top)

Supported Formats

Image overlays support the following formats:

PNG - Best for logos and images with transparency
JPEG/JPG - Best for photos and images without transparency

PNG Transparency: PNG images with transparent backgrounds are fully supported. The transparent areas will show the video beneath.

Position Configuration

Control where your image appears on the video.

Anchor-Based Positioning

Use predefined anchor positions for quick placement:

interface PositionConfig {
  anchor:
    | 'top-left'
    | 'top-center'
    | 'top-right'
    | 'center-left'
    | 'center'
    | 'center-right'
    | 'bottom-left'
    | 'bottom-center'
    | 'bottom-right';
}

Visual Guide:

┌───────────────────────────────────────┐
│  TL          TC           TR          │
│   ●           ●            ●          │
│                                       │
│                                       │
│  CL          C            CR          │
│   ●           ●            ●          │
│                                       │
│                                       │
│  BL          BC           BR          │
│   ●           ●            ●          │
└───────────────────────────────────────┘

TL = top-left        TC = top-center      TR = top-right
CL = center-left     C  = center          CR = center-right
BL = bottom-left     BC = bottom-center   BR = bottom-right

Example:

{
  "type": "image",
  "url": "https://example.com/logo.png",
  "position": { "anchor": "top-right" }
}

Percentage-Based Positioning

Use x/y percentages for precise control:

interface PositionConfig {
  x: string; // "0%" to "100%"
  y: string; // "0%" to "100%"
}

x: "0%" = Left edge
x: "50%" = Horizontal center
x: "100%" = Right edge
y: "0%" = Top edge
y: "50%" = Vertical center
y: "100%" = Bottom edge

Example:

{
  "type": "image",
  "url": "https://example.com/logo.png",
  "position": {
    "x": "85%",
    "y": "15%"
  }
}

Use either anchor OR x/y, not both. If both are provided, anchor takes precedence.

Size Configuration

Control the dimensions of your image overlay.

interface SizeConfig {
  width?: number | string; // Pixels or percentage
  height?: number | string; // Pixels or percentage
  fit?: 'cover' | 'contain'; // How to fit the image
}

Width and Height

Specify size using pixels or percentages:

Pixels:

{
  "size": {
    "width": 200,
    "height": 100
  }
}

Percentages:

{
  "size": {
    "width": "20%",
    "height": "10%"
  }
}

Width only (maintains aspect ratio):

{
  "size": {
    "width": "15%"
  }
}

Fit Modes

Control how the image fits within the specified dimensions:

Fit Mode	Behavior
`contain`	Image fits within dimensions, maintains aspect ratio, may have empty space
`cover`	Image fills dimensions completely, maintains aspect ratio, may crop

Contain Example:

{
  "size": {
    "width": 400,
    "height": 400,
    "fit": "contain"
  }
}

Result: A 800x400 image will be scaled to 400x200, centered within the 400x400 space.

Cover Example:

{
  "size": {
    "width": 400,
    "height": 400,
    "fit": "cover"
  }
}

Result: A 800x400 image will be scaled to 800x400 and cropped to 400x400.

Timing Configuration

Control when the image appears in your video.

interface TimingConfig {
  startTime?: number; // Start time in seconds
  endTime?: number; // End time in seconds
  entireVideo?: boolean; // Show for entire video
}

Entire Video

Show the image for the entire video duration:

{
  "timing": {
    "entireVideo": true
  }
}

Time Range

Show the image for a specific time range:

{
  "timing": {
    "startTime": 5,
    "endTime": 15
  }
}

This shows the image from 5 seconds to 15 seconds (10 seconds total).

From Start

Show from the beginning for a specific duration:

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

Visual Effects

Add opacity and fade transitions to your images.

interface VisualEffects {
  opacity?: number; // 0 (transparent) to 1 (opaque)
  fadeIn?: FadeConfig; // Fade in transition
  fadeOut?: FadeConfig; // Fade out transition
}

interface FadeConfig {
  duration: number; // Duration in seconds
  easing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
}

Opacity

Control the transparency of the image:

{
  "effects": {
    "opacity": 0.7
  }
}

0 = Completely transparent (invisible)
0.5 = 50% transparent
1 = Completely opaque (default)

Fade In

Smoothly fade in the image when it appears:

{
  "effects": {
    "fadeIn": {
      "duration": 1.5,
      "easing": "ease-in"
    }
  }
}

Fade Out

Smoothly fade out the image when it disappears:

{
  "effects": {
    "fadeOut": {
      "duration": 2,
      "easing": "ease-out"
    }
  }
}

Combined Effects

Use multiple effects together:

{
  "effects": {
    "opacity": 0.8,
    "fadeIn": {
      "duration": 1,
      "easing": "ease-in"
    },
    "fadeOut": {
      "duration": 1.5,
      "easing": "ease-out"
    }
  }
}

Easing Functions

Easing	Behavior
`linear`	Constant rate of change
`ease-in`	Starts slow, ends fast
`ease-out`	Starts fast, ends slow
`ease-in-out`	Starts slow, fast in middle, ends slow

Z-Index Layering

Control the stacking order when using multiple elements:

{
  "zIndex": 10
}

Higher values appear on top of lower values:

zIndex: 1 - Bottom layer
zIndex: 5 - Middle layer
zIndex: 10 - Top layer

Tip: Use increments of 10 (10, 20, 30) to make it easier to insert new elements between existing layers later.

Complete Examples

Simple Watermark

Add a watermark to the bottom-right corner:

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": "image",
        "url": "https://example.com/watermark.png",
        "timing": { "entireVideo": true },
        "position": { "anchor": "bottom-right" },
        "size": { "width": "10%" },
        "effects": { "opacity": 0.7 },
        "zIndex": 100
      }
    ]
  }'

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: 'image',
        url: 'https://example.com/watermark.png',
        timing: { entireVideo: true },
        position: { anchor: 'bottom-right' },
        size: { width: '10%' },
        effects: { opacity: 0.7 },
        zIndex: 100,
      },
    ],
  }),
});

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': 'image',
                'url': 'https://example.com/watermark.png',
                'timing': {'entireVideo': True},
                'position': {'anchor': 'bottom-right'},
                'size': {'width': '10%'},
                'effects': {'opacity': 0.7},
                'zIndex': 100,
            },
        ],
    }
)

data = response.json()
print(f"Video ID: {data['videoId']}")

interface ImageElement {
  type: 'image';
  url: string;
  timing: { entireVideo: boolean };
  position: { anchor: string };
  size: { width: string };
  effects?: { opacity: number };
  zIndex?: number;
}

const watermark: ImageElement = {
type: 'image',
url: 'https://example.com/watermark.png',
timing: { entireVideo: true },
position: { anchor: 'bottom-right' },
size: { width: '10%' },
effects: { opacity: 0.7 },
zIndex: 100,
};

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: [watermark],
}),
});

const data = await response.json();
console.log(`Video ID: ${data.videoId}`);

Logo with Fade Transitions

Add a logo that fades in and out:

{
  "fileUrl": "https://example.com/video.mp4",
  "elements": [
    {
      "type": "image",
      "url": "https://example.com/logo.png",
      "timing": {
        "startTime": 0,
        "endTime": 5
      },
      "position": { "anchor": "top-left" },
      "size": { "width": "20%" },
      "effects": {
        "fadeIn": {
          "duration": 1,
          "easing": "ease-in"
        },
        "fadeOut": {
          "duration": 1,
          "easing": "ease-out"
        }
      },
      "zIndex": 10
    }
  ]
}

Lower Third Name Plate

Add a lower third with precise positioning:

{
  "type": "image",
  "url": "https://example.com/lower-third.png",
  "timing": {
    "startTime": 2,
    "endTime": 8
  },
  "position": {
    "x": "50%",
    "y": "85%"
  },
  "size": {
    "width": "60%"
  },
  "effects": {
    "fadeIn": {
      "duration": 0.5,
      "easing": "ease-in-out"
    },
    "fadeOut": {
      "duration": 0.5,
      "easing": "ease-in-out"
    }
  },
  "zIndex": 20
}

Multiple Layered Images

Create a complex composition with multiple images:

{
  "fileUrl": "https://example.com/video.mp4",
  "elements": [
    {
      "type": "image",
      "url": "https://example.com/background-frame.png",
      "timing": { "entireVideo": true },
      "position": { "anchor": "center" },
      "size": { "width": "100%" },
      "effects": { "opacity": 0.3 },
      "zIndex": 1
    },
    {
      "type": "image",
      "url": "https://example.com/logo.png",
      "timing": { "entireVideo": true },
      "position": { "anchor": "top-center" },
      "size": { "width": "25%" },
      "zIndex": 10
    },
    {
      "type": "image",
      "url": "https://example.com/watermark.png",
      "timing": { "entireVideo": true },
      "position": { "anchor": "bottom-right" },
      "size": { "width": "12%" },
      "effects": { "opacity": 0.6 },
      "zIndex": 100
    }
  ]
}

Common Use Cases

Company Watermark

Protect your content with a semi-transparent watermark:

{
  "type": "image",
  "url": "https://cdn.example.com/watermark.png",
  "timing": { "entireVideo": true },
  "position": { "anchor": "bottom-right" },
  "size": { "width": "15%" },
  "effects": { "opacity": 0.5 },
  "zIndex": 999
}

Corner Logo

Add your logo to the corner with subtle opacity:

{
  "type": "image",
  "url": "https://cdn.example.com/brand-logo.png",
  "timing": { "entireVideo": true },
  "position": { "anchor": "top-right" },
  "size": { "width": "12%" },
  "effects": { "opacity": 0.9 },
  "zIndex": 50
}

Intro Splash Screen

Show an intro image for the first few seconds:

{
  "type": "image",
  "url": "https://cdn.example.com/intro-splash.png",
  "timing": {
    "startTime": 0,
    "endTime": 3
  },
  "position": { "anchor": "center" },
  "size": { "width": "80%" },
  "effects": {
    "fadeIn": { "duration": 0.5 },
    "fadeOut": { "duration": 0.5 }
  },
  "zIndex": 100
}

Add your social media handle overlay:

{
  "type": "image",
  "url": "https://cdn.example.com/social-handle.png",
  "timing": { "entireVideo": true },
  "position": { "anchor": "bottom-center" },
  "size": { "width": "20%" },
  "effects": { "opacity": 0.85 },
  "zIndex": 75
}

Call-to-Action Overlay

Add a CTA at the end of the video:

{
  "type": "image",
  "url": "https://cdn.example.com/cta-subscribe.png",
  "timing": {
    "startTime": 55,
    "endTime": 60
  },
  "position": { "anchor": "center" },
  "size": { "width": "50%" },
  "effects": {
    "fadeIn": {
      "duration": 0.5,
      "easing": "ease-in"
    }
  },
  "zIndex": 90
}

Optimize your images before uploading to reduce processing time and improve quality: - Use appropriate resolution (don't use 4K images for small overlays) - Compress images without losing quality - Use PNG for logos and transparency, JPEG for photos - Remove unnecessary metadata

Sizing Strategy

Use percentages for responsive layouts:

{ "size": { "width": "15%" } }

This ensures your overlay looks good across different video resolutions.

Use pixels for precise control:

{ "size": { "width": 200, "height": 100 } }

Best when you know the exact output resolution.

Position Strategy

Safe zones: Keep important content away from edges (5-10% margin):

{
  "position": { "x": "10%", "y": "10%" }
}

Test different aspect ratios: Your overlay should look good on 16:9, 9:16, and 1:1 videos.

Performance Tips

Limit overlay count: Each image adds processing time
Use appropriate file sizes: Smaller files process faster
Pre-render complex graphics: Don't rely on real-time scaling
Cache frequently used images: Host on a fast CDN

Quality Guidelines

For watermarks:

Opacity: 0.5 - 0.7
Size: 10-15% of video width
Position: Corner placement
Format: PNG with transparency

For logos:

Opacity: 0.8 - 1.0
Size: 15-25% of video width
Position: Top corners or center
Format: PNG for transparency

For lower thirds:

Opacity: 0.9 - 1.0
Size: 50-80% of video width
Position: Bottom 15-25% of height
Format: PNG with transparency

Timing Best Practices

Fade transitions: Always use fade in/out for professional look:

{
  "effects": {
    "fadeIn": { "duration": 0.5, "easing": "ease-in-out" },
    "fadeOut": { "duration": 0.5, "easing": "ease-in-out" }
  }
}

Timing alignment: Align image timing with video content:

Show names when person speaks
Display CTAs during pauses
Add branding at key moments

Troubleshooting

Image Not Appearing

Check these common issues:

URL is publicly accessible (test in browser)
Image format is supported (PNG, JPEG)
Timing is within video duration
Size is not 0 or negative
Opacity is not 0

Image Looks Distorted

Solutions:

Use fit: "contain" to maintain aspect ratio
Provide only width OR height, not both
Check source image aspect ratio
Verify size percentages are reasonable

Image is Clipped

Solutions:

Use percentage-based sizing
Check position values (0-100%)
Verify image fits within video bounds
Test with safe zone margins

Poor Image Quality

Solutions:

Use higher resolution source images
Avoid upscaling small images
Use PNG for sharp graphics
Compress without losing quality

Image Overlays

GIF Overlays

Video Overlays

Audio Overlays

Examples

On this page