Video Composition via API

Automatically compose your transparent videos on custom backgrounds - all processed on our servers. No need to handle transparent videos yourself.

New: Try our Composition Builder to design compositions visually and export JSON.

Perfect for: Automation workflows (n8n, Zapier), applications that need final videos immediately, and users who don’t want to deal with transparent video formats.

What is API Composition?

Instead of receiving a transparent video that you need to compose yourself, the API can automatically layer your foreground on a custom background and return the final video. Two modes:

Templates - Quick presets for common layouts (social media ads, centered, PiP, fullscreen)
Custom - Full control over positioning, sizing, and effects

Quick Start with Templates

Templates are pre-configured compositions optimized for common use cases.

Available Templates

🎯 AI UGC Ad

Optimized for social media ads (9:16 vertical)

Centered foreground
Contain sizing
Perfect for TikTok, Instagram Reels

📱 Centered

Simple centered layout

Foreground in center
Fits within canvas
Universal use case

🖼️ Picture in Picture

Small overlay in corner

Bottom-right position
30% canvas size
News, commentary style

📺 Fullscreen

Cover entire canvas

Foreground fills screen
May crop to fit
Immersive experience

Template Example

curl -X POST https://api.videobgremover.com/v1/jobs/JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "composition",
      "composition": {
        "template": "ai_ugc_ad",
        "background_url": "https://example.com/background.mp4",
        "background_type": "video",
        "background_audio_enabled": true,
        "background_audio_volume": 0.8
      }
    }
  }'

SDK Support Coming Soon: Python and Node.js SDK clients will support composition in an upcoming release. For now, use direct HTTP requests as shown above.

Custom Composition

Full control over positioning, sizing, and effects.

Basic Custom Composition

curl -X POST https://api.videobgremover.com/v1/jobs/JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "composition",
      "composition": {
        "background_url": "https://example.com/background.jpg",
        "background_type": "image",
        "position": "center",
        "size_mode": "canvas_percent",
        "size_percent": 50,
        "opacity": 1.0,
        "export_format": "h264",
        "export_crf": 23
      }
    }
  }'

curl -X POST https://api.videobgremover.com/v1/jobs/JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "composition",
      "composition": {
        "background_url": "https://example.com/background.mp4",
        "background_type": "video",
        "background_audio_enabled": true,
        "background_audio_volume": 1.0,
        "position": "bottom_right",
        "size_mode": "canvas_percent",
        "size_percent": 30,
        "offset_x": -20,
        "offset_y": -20,
        "opacity": 0.95
      }
    }
  }'

Positioning

Control where your foreground appears on the canvas.

Anchor Points

Choose from 9 anchor positions:

📍 top_left

📍 top_center

📍 top_right

📍 center_left

📍 center

📍 center_right

📍 bottom_left

📍 bottom_center

📍 bottom_right

Pixel Offsets

Fine-tune position with pixel offsets from the anchor:

{
  "position": "bottom_right",
  "offset_x": -20,  // 20px from right edge
  "offset_y": -20   // 20px from bottom edge
}

Positioning Examples

Centered
Top-Right Corner
Bottom-Left

{
  "position": "center",
  "offset_x": 0,
  "offset_y": 0
}

Perfect for standard layouts

{
  "position": "top_right",
  "offset_x": -10,
  "offset_y": 10
}

Logo or watermark placement

{
  "position": "bottom_left",
  "offset_x": 20,
  "offset_y": -20
}

Commentary or reaction video style

Sizing Modes

Control how your foreground is sized on the canvas.

Size Mode Reference

Mode	Description	Use Case	Parameters
`contain`	Fit within canvas, preserve aspect ratio	Default, safe choice	None
`cover`	Fill canvas, preserve aspect ratio (may crop)	Full coverage	None
`canvas_percent`	Size as % of canvas	Precise control	`size_percent`
`px`	Exact pixel dimensions	Fixed size	`size_width`, `size_height`
`scale`	Scale relative to original	Proportional resize	`size_width`, `size_height` as scale factors
`fit_width`	Fit to canvas width	Full width	None
`fit_height`	Fit to canvas height	Full height	None

Sizing Examples

Contain (Default)
50% Canvas Size
Exact Pixels
Scale 75%

{
  "size_mode": "contain"
}

Foreground fits within canvas, no cropping

{
  "size_mode": "canvas_percent",
  "size_percent": 50
}

Foreground is 50% of canvas dimensions

{
  "size_mode": "px",
  "size_width": 640,
  "size_height": 480
}

Foreground is exactly 640x480px

{
  "size_mode": "scale",
  "size_width": 0.75,
  "size_height": 0.75
}

Foreground scaled to 75% of original size

Background Types

Image Backgrounds

Static image backgrounds (JPEG, PNG):

{
  "background_url": "https://example.com/background.jpg",
  "background_type": "image"
}

Perfect for: Product showcases, simple layouts, photos

Video Backgrounds

Animated video backgrounds (MP4, WebM):

{
  "background_url": "https://example.com/background.mp4",
  "background_type": "video",
  "background_audio_enabled": true,
  "background_audio_volume": 0.7
}

Perfect for: Dynamic content, ads, music videos

Audio Mixing: When background_audio_enabled: true, both background and foreground audio are mixed together. Adjust background_audio_volume (0.0 to 1.0) to balance the mix.

Advanced Options

Opacity Control

Control foreground transparency:

{
  "opacity": 0.85
}

Values: 0.0 (fully transparent) to 1.0 (fully opaque) Use cases:

Watermarks (0.3 - 0.5)
Subtle overlays (0.6 - 0.8)
Normal composition (1.0)

Export Quality

Control output video quality:

{
  "export_format": "h264",
  "export_crf": 23
}

CRF Values:

18 - Very high quality (larger files)
23 - High quality (default, recommended)
28 - Medium quality (smaller files)
32 - Lower quality (smallest files)

CRF (Constant Rate Factor): Lower values = better quality + larger files. Range: 0-51, default: 23.

Complete Examples

#!/bin/bash
API_KEY="vbr_your_api_key"
VIDEO_URL="https://example.com/product-demo.mp4"
BG_VIDEO="https://example.com/trendy-background.mp4"

# 1. Create job
JOB=$(curl -s -X POST https://api.videobgremover.com/v1/jobs \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"video_url\": \"$VIDEO_URL\"}")

JOB_ID=$(echo $JOB | jq -r '.id')
echo "Created job: $JOB_ID"

# 2. Start processing with composition
curl -X POST https://api.videobgremover.com/v1/jobs/$JOB_ID/start \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "background": {
      "type": "composition",
      "composition": {
        "template": "ai_ugc_ad",
        "background_url": "'"$BG_VIDEO"'",
        "background_type": "video",
        "background_audio_enabled": true,
        "background_audio_volume": 0.6
      }
    }
  }'

# 3. Poll for completion
while true; do
  STATUS=$(curl -s -X GET https://api.videobgremover.com/v1/jobs/$JOB_ID/status \
    -H "X-Api-Key: $API_KEY" | jq -r '.status')
  
  if [ "$STATUS" = "completed" ]; then
    VIDEO_URL=$(curl -s -X GET https://api.videobgremover.com/v1/jobs/$JOB_ID/status \
      -H "X-Api-Key: $API_KEY" | jq -r '.processed_video_url')
    
    echo "✅ Composition complete!"
    echo "Download: $VIDEO_URL"
    break
  fi
  
  echo "Status: $STATUS - waiting..."
  sleep 10
done

Python & Node.js SDK: Composition support will be added to the SDK clients in an upcoming release. Use direct HTTP requests (cURL, axios, requests, etc.) for now.

Picture-in-Picture News Style

{
  "background": {
    "type": "composition",
    "composition": {
      "background_url": "https://example.com/news-background.jpg",
      "background_type": "image",
      "position": "bottom_right",
      "size_mode": "canvas_percent",
      "size_percent": 25,
      "offset_x": -30,
      "offset_y": -30,
      "opacity": 1.0
    }
  }
}

Watermark Overlay

{
  "background": {
    "type": "composition",
    "composition": {
      "background_url": "https://example.com/main-video.mp4",
      "background_type": "video",
      "position": "top_right",
      "size_mode": "canvas_percent",
      "size_percent": 15,
      "offset_x": -20,
      "offset_y": 20,
      "opacity": 0.4
    }
  }
}

Parameter Reference

Composition Object (Template)

Parameter	Type	Required	Default	Description
`template`	string	✅ Yes	-	Template name: `ai_ugc_ad`, `centered`, `picture_in_picture`, `fullscreen`
`background_url`	string	✅ Yes	-	URL to background image/video
`background_type`	string	No	auto-detect	`image` or `video`
`background_audio_enabled`	boolean	No	`false`	Enable background audio (video only)
`background_audio_volume`	number	No	`1.0`	Audio volume (0.0 to 1.0)
`export_format`	string	No	`h264`	Export codec
`export_crf`	integer	No	`23`	Quality (0-51, lower = better)

Composition Object (Custom)

Parameter	Type	Required	Default	Description
`background_url`	string	✅ Yes	-	URL to background
`background_type`	string	✅ Yes	-	`color`, `image`, or `video`
`background_color`	string	Conditional	-	Hex color (if type is `color`)
`background_audio_enabled`	boolean	No	`false`	Enable audio
`background_audio_volume`	number	No	`1.0`	Volume (0.0-1.0)
`position`	string	No	`center`	Anchor point
`offset_x`	integer	No	`0`	Horizontal offset (px)
`offset_y`	integer	No	`0`	Vertical offset (px)
`size_mode`	string	No	`contain`	Sizing mode
`size_percent`	number	Conditional	-	Size % (if mode is `canvas_percent`)
`size_width`	number	Conditional	-	Width value
`size_height`	number	Conditional	-	Height value
`opacity`	number	No	`1.0`	Opacity (0.0-1.0)
`export_format`	string	No	`h264`	Export codec
`export_crf`	integer	No	`23`	Quality (0-51)

Common Issues

Background URL Not Accessible

Problem: Composition fails with “Cannot download background” Solution: Ensure background URL is:

✅ Publicly accessible (no authentication required)
✅ Direct file link (not a webpage)
✅ Supported format (JPEG, PNG for images; MP4, WebM for videos)

Audio Not Playing

Problem: Background audio is silent in final video Solution:

{
  "background_audio_enabled": true,  // Must be true
  "background_audio_volume": 1.0     // 0.0 = silent, 1.0 = full volume
}

Foreground Too Small/Large

Problem: Foreground doesn’t fit properly Solution: Try different size modes:

contain - Safest, fits within canvas
canvas_percent with size_percent: 80 - 80% of canvas
Adjust size_percent value until it looks right

Position Not Accurate

Problem: Foreground not in expected position Solution: Use offset adjustments:

{
  "position": "bottom_right",
  "offset_x": -50,  // Move 50px from right edge
  "offset_y": -50   // Move 50px from bottom edge
}

Next Steps

API Endpoints

Complete REST API reference

SDK Composition

Advanced local composition with multiple layers

Examples

More code examples and use cases

Output Formats

Learn about transparent video formats

​Video Composition via API

​What is API Composition?

​Quick Start with Templates

​Available Templates

🎯 AI UGC Ad

📱 Centered

🖼️ Picture in Picture

📺 Fullscreen

​Template Example

​Custom Composition

​Basic Custom Composition

​Positioning

​Anchor Points

​Pixel Offsets

​Positioning Examples

​Sizing Modes

​Size Mode Reference

​Sizing Examples

​Background Types

​Image Backgrounds

​Video Backgrounds

​Advanced Options

​Opacity Control

​Export Quality

​Complete Examples

​Social Media Ad Workflow

​Picture-in-Picture News Style

​Watermark Overlay

​Parameter Reference

​Composition Object (Template)

​Composition Object (Custom)

​Common Issues

​Background URL Not Accessible

​Audio Not Playing

​Foreground Too Small/Large

​Position Not Accurate

​Next Steps

API Endpoints

SDK Composition

Examples

Output Formats

Video Composition via API

What is API Composition?

Quick Start with Templates

Available Templates

Template Example

Custom Composition

Basic Custom Composition

Positioning

Anchor Points

Pixel Offsets

Positioning Examples

Sizing Modes

Size Mode Reference

Sizing Examples

Background Types

Image Backgrounds

Video Backgrounds

Advanced Options

Opacity Control

Export Quality

Complete Examples

Social Media Ad Workflow

Picture-in-Picture News Style

Watermark Overlay

Parameter Reference

Composition Object (Template)

Composition Object (Custom)

Common Issues

Background URL Not Accessible

Audio Not Playing

Foreground Too Small/Large

Position Not Accurate

Next Steps