> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videobgremover.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Video Composition via API

> Compose videos on custom backgrounds using server-side processing. Perfect for automation, n8n workflows, and applications that need ready-to-use videos.

# Video Composition via API

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

<Tip>
  **New:** Try our [Composition Builder](https://videobgremover.com/composition-builder) to design compositions visually and export JSON.
</Tip>

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

## 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:**

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

***

## Quick Start with Templates

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

### Available Templates

<CardGroup cols={2}>
  <Card title="🎯 AI UGC Ad" icon="mobile-screen">
    Optimized for social media ads (9:16 vertical)

    * Centered foreground
    * Contain sizing
    * Perfect for TikTok, Instagram Reels
  </Card>

  <Card title="📱 Centered" icon="align-center">
    Simple centered layout

    * Foreground in center
    * Fits within canvas
    * Universal use case
  </Card>

  <Card title="🖼️ Picture in Picture" icon="image">
    Small overlay in corner

    * Bottom-right position
    * 30% canvas size
    * News, commentary style
  </Card>

  <Card title="📺 Fullscreen" icon="expand">
    Cover entire canvas

    * Foreground fills screen
    * May crop to fit
    * Immersive experience
  </Card>
</CardGroup>

### Template Example

```bash theme={"dark"}
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
      }
    }
  }'
```

<Info>
  **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.
</Info>

***

## Custom Composition

Full control over positioning, sizing, and effects.

### Basic Custom Composition

<CodeGroup>
  ```bash cURL - Image Background theme={"dark"}
  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
        }
      }
    }'
  ```

  ```bash cURL - Video Background theme={"dark"}
  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
        }
      }
    }'
  ```
</CodeGroup>

***

## Positioning

Control where your foreground appears on the canvas.

### Anchor Points

Choose from 9 anchor positions:

<div style={{display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '10px', textAlign: 'center', margin: '20px 0'}}>
  <div>📍 `top_left`</div>
  <div>📍 `top_center`</div>
  <div>📍 `top_right`</div>
  <div>📍 `center_left`</div>
  <div>📍 `center`</div>
  <div>📍 `center_right`</div>
  <div>📍 `bottom_left`</div>
  <div>📍 `bottom_center`</div>
  <div>📍 `bottom_right`</div>
</div>

### Pixel Offsets

Fine-tune position with pixel offsets from the anchor:

```json theme={"dark"}
{
  "position": "bottom_right",
  "offset_x": -20,  // 20px from right edge
  "offset_y": -20   // 20px from bottom edge
}
```

### Positioning Examples

<Tabs>
  <Tab title="Centered">
    ```json theme={"dark"}
    {
      "position": "center",
      "offset_x": 0,
      "offset_y": 0
    }
    ```

    Perfect for standard layouts
  </Tab>

  <Tab title="Top-Right Corner">
    ```json theme={"dark"}
    {
      "position": "top_right",
      "offset_x": -10,
      "offset_y": 10
    }
    ```

    Logo or watermark placement
  </Tab>

  <Tab title="Bottom-Left">
    ```json theme={"dark"}
    {
      "position": "bottom_left",
      "offset_x": 20,
      "offset_y": -20
    }
    ```

    Commentary or reaction video style
  </Tab>
</Tabs>

***

## 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

<Tabs>
  <Tab title="Contain (Default)">
    ```json theme={"dark"}
    {
      "size_mode": "contain"
    }
    ```

    Foreground fits within canvas, no cropping
  </Tab>

  <Tab title="50% Canvas Size">
    ```json theme={"dark"}
    {
      "size_mode": "canvas_percent",
      "size_percent": 50
    }
    ```

    Foreground is 50% of canvas dimensions
  </Tab>

  <Tab title="Exact Pixels">
    ```json theme={"dark"}
    {
      "size_mode": "px",
      "size_width": 640,
      "size_height": 480
    }
    ```

    Foreground is exactly 640x480px
  </Tab>

  <Tab title="Scale 75%">
    ```json theme={"dark"}
    {
      "size_mode": "scale",
      "size_width": 0.75,
      "size_height": 0.75
    }
    ```

    Foreground scaled to 75% of original size
  </Tab>
</Tabs>

***

## Background Types

### Image Backgrounds

Static image backgrounds (JPEG, PNG):

```json theme={"dark"}
{
  "background_url": "https://example.com/background.jpg",
  "background_type": "image"
}
```

**Perfect for:** Product showcases, simple layouts, photos

### Video Backgrounds

Animated video backgrounds (MP4, WebM):

```json theme={"dark"}
{
  "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

<Warning>
  **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.
</Warning>

***

## Advanced Options

### Opacity Control

Control foreground transparency:

```json theme={"dark"}
{
  "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:

```json theme={"dark"}
{
  "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)

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

***

## Complete Examples

### Social Media Ad Workflow

```bash theme={"dark"}
#!/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
```

<Note>
  **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.
</Note>

### Picture-in-Picture News Style

```json theme={"dark"}
{
  "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

```json theme={"dark"}
{
  "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:**

```json theme={"dark"}
{
  "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:

```json theme={"dark"}
{
  "position": "bottom_right",
  "offset_x": -50,  // Move 50px from right edge
  "offset_y": -50   // Move 50px from bottom edge
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="API Endpoints" icon="code" href="/api-reference/all-endpoints">
    Complete REST API reference
  </Card>

  <Card title="SDK Composition" icon="layer-group" href="/video-composition/overview">
    Advanced local composition with multiple layers
  </Card>

  <Card title="Examples" icon="book" href="/examples">
    More code examples and use cases
  </Card>

  <Card title="Output Formats" icon="file-video" href="/video-background-removal/output-formats">
    Learn about transparent video formats
  </Card>
</CardGroup>