ReelForger LogoDocumentation
Sign inGet Started

Working with Images

Image layers allow you to render static .jpg, .png, or .webp files over time. They are incredibly powerful when combined with the layout object for Picture-in-Picture, logos, or watermarks.

Basic Image Object

An image layer needs an asset_id and a time definition. time.start_seconds is required. time.duration_seconds is optional when ReelForger can infer overall composition duration from other data.

Duration Inference Precedence

When image time.duration_seconds is omitted, ReelForger resolves timing in this order:

  1. If image time.duration_seconds is provided, that explicit value is used.
  2. Otherwise, if composition.duration_seconds is provided, image duration is inferred as:
    • composition.duration_seconds - image.time.start_seconds
  3. Otherwise, composition duration is inferred from the maximum timed end across composition.timeline and composition.text_overlays, then image duration is inferred from that result.
  4. Otherwise, if composition.auto_stitch is enabled and untimed audio/video layers are present, ReelForger can probe those media durations at render time and then infer the image duration.

If none of the above can establish a valid duration, validation fails with a clear error.

{
  "id": "watermark-logo",
  "type": "image",
  "asset_id": "asset-logo-1",
  "time": {
    "start_seconds": 0,
    "duration_seconds": 60
  }
}

Spatial Coordinates (layout)

To position an image, supply a layout object. The layout allows you to define standard CSS-like spatial bounds.

  • x: Horizontal position (e.g., "10%", "20px"). Maps to the CSS left property.
  • y: Vertical position (e.g., "10%", "20px"). Maps to the CSS top property.
  • width: The width of the bounding box.
  • height: The height of the bounding box.
  • fit: How the image fits inside its bounding box ("cover" or "contain"). Default is "cover".
{
  "id": "logo-top-right",
  "type": "image",
  "asset_id": "asset-logo-1",
  "layout": {
    "x": "80%",
    "y": "5%",
    "width": "15%",
    "height": "10%",
    "fit": "contain"
  }
}

Background Mode (background_mode)

Similar to Videos, images support background_mode. If your image does not perfectly match its layout bounding box, you can control the empty space.

Allowed values:

  • "blurred": default
  • "transparent"
  • "solid"

For things like transparent .png logos, you should always explicitly set "background_mode": "transparent", otherwise they will render with a blurred background copy of themselves.

{
  "id": "transparent-logo",
  "type": "image",
  "asset_id": "asset-logo-1",
  "background_mode": "transparent",
  "layout": {
    "x": "10px",
    "y": "10px",
    "width": "100px",
    "height": "100px",
    "fit": "contain"
  }
}

Styling Images

The style object uses snake_case keys (consistent with the rest of the manifest):

  • opacity (number, 0–1)
  • border_radius (string, e.g. "24px")
  • box_shadow (string, e.g. "0 10px 30px rgba(0,0,0,0.5)")
  • transform (string, CSS-like transform expression)

style.transform is supported, but keep it intentional. Prefer layout for placement and size, and use transform only for final visual adjustments such as slight rotate/scale treatment.

{
  "id": "styled-image",
  "type": "image",
  "asset_id": "asset-pic",
  "style": {
    "opacity": 0.8,
    "border_radius": "24px",
    "box_shadow": "0 10px 30px rgba(0,0,0,0.5)"
  }
}

Motion

Images support the motion field for lightweight Ken Burns style movement. Allowed values:

  • zoom_in
  • zoom_out
  • pan_left
  • pan_right
  • none (default)

The Full Image Request Example

This example places a transparent PNG logo in the top right corner of the video for the entire 10-second duration.

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-bg-video",
          "type": "video",
          "url": "https://example.com/background.mp4"
        },
        {
          "id": "asset-logo",
          "type": "image",
          "url": "https://example.com/logo.png"
        }
    ],
    "composition": {
        "timeline": [
          {
            "id": "base-video",
            "type": "video",
            "asset_id": "asset-bg-video",
            "time": {
              "start_seconds": 0,
              "duration_seconds": 10
            }
          },
          {
            "id": "overlay-logo",
            "type": "image",
            "asset_id": "asset-logo",
            "background_mode": "transparent",
            "time": {
              "start_seconds": 0,
              "duration_seconds": 10
            },
            "layout": {
              "x": "80%",
              "y": "5%",
              "width": "15%",
              "height": "10%",
              "fit": "contain",
              "z_index": 10
            }
          }
        ]
    }
  }'
ReelForger