Working with Video

Video layers are the foundation of most ReelForger compositions. They allow you to place video assets onto the timeline, optionally trimming them, and controlling how they scale within your composition.

Basic Video Object

A basic video layer requires an id, type, asset_id, and time positioning. When is time required? For video layers, time is required unless composition.auto_stitch is true—in that case, video timing is derived automatically from clip order. Audio layers can also omit time with auto-stitch, but mixed video+audio behavior differs (audio defaults to start at 0 unless explicitly timed).

{
  "id": "main-video",
  "type": "video",
  "asset_id": "asset-video-1",
  "time": {
    "start_seconds": 0,
    "duration_seconds": 5
  }
}

Auto-Stitching & Arrays

If you don't want to calculate exact timeline mathematics (start_seconds), ReelForger supports auto_stitch. When enabled on the root composition object, you can omit the time property from video layers. ReelForger will probe durations and play clips in timeline order.

This also works for a single base video clip (for example: talking-head + logo overlay) when you do not want to precompute duration.

{
  "composition": {
    "auto_stitch": true,
    "timeline": [
      {
        "id": "clip-1",
        "type": "video",
        "asset_id": "asset-video-1"
      },
      {
        "id": "clip-2",
        "type": "video",
        "asset_id": "asset-video-2"
      }
    ]
  }
}

Trim vs Timeline Time

time controls where a layer lives in the final composition. trim controls where playback starts inside the source media.

{
  "id": "clipped-intro",
  "type": "video",
  "asset_id": "asset-video-1",
  "time": {
    "start_seconds": 0,
    "duration_seconds": 4
  },
  "trim": {
    "start_seconds": 12
  }
}

That example places a 4-second layer at the start of the final composition, but it begins playback 12 seconds into the source video.

Single Talking-Head + Logo (No Manual Duration)

You can omit the base video duration and let ReelForger infer it with auto_stitch.

{
  "composition": {
    "auto_stitch": true,
    "timeline": [
      {
        "id": "base-video",
        "type": "video",
        "asset_id": "asset-video-1"
      },
      {
        "id": "logo-overlay",
        "type": "image",
        "asset_id": "asset-logo-1",
        "time": { "start_seconds": 0 },
        "background_mode": "transparent",
        "layout": {
          "x": "82%",
          "y": "88%",
          "width": "12%",
          "height": "8%",
          "fit": "contain",
          "z_index": 20
        }
      }
    ]
  }
}

Z-Index Stacking

By default, layers are drawn back-to-front based on their order in the timeline array. The first layer is the bottom-most background, and the last layer is on top. You can explicitly override this by providing a z_index inside the layout object.

{
  "id": "foreground-video",
  "type": "video",
  "asset_id": "asset-video-1",
  "layout": {
    "z_index": 100
  }
}

Background Mode & Letterboxing

When you place a video with a different aspect ratio than your composition (e.g., a 16:9 landscape video into a 9:16 portrait composition), ReelForger must pad the empty space.

You can control this using the background_mode property:

• "blurred" (Default): Creates a cinematic blurred and zoomed version of your video to fill the background.
• "solid": Fills the empty space with a solid black background.
• "transparent": Leaves the empty space transparent, allowing layers beneath it (lower z-index) to show through.

{
  "id": "landscape-clip",
  "type": "video",
  "asset_id": "asset-landscape-video",
  "background_mode": "blurred",
  "layout": {
    "fit": "contain"
  }
}

Common enums and media settings

Available video media_settings keys:

transitions is schema-visible on layers, but explicit timing is still the recommended primary authoring surface in the public docs.

The Full Video Request Example

Here is a complete payload placing two videos sequentially using explicit timings, with the first video using a solid background mode.

curl -X POST https://api.reelforger.com/v1/videos/render \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v1",
    "output": {
      "width": 1080,
      "height": 1920,
      "fps": 30
    },
    "assets": [
        {
          "id": "asset-1",
          "type": "video",
          "url": "https://example.com/video1.mp4"
        },
        {
          "id": "asset-2",
          "type": "video",
          "url": "https://example.com/video2.mp4"
        }
      ],
      "composition": {
        "timeline": [
          {
            "id": "layer-1",
            "type": "video",
            "asset_id": "asset-1",
            "background_mode": "solid",
            "time": {
              "start_seconds": 0,
              "duration_seconds": 5
            }
          },
          {
            "id": "layer-2",
            "type": "video",
            "asset_id": "asset-2",
            "time": {
              "start_seconds": 5,
              "duration_seconds": 5
            }
          }
        ]
    }
  }'