Image Examples

Each example is a complete POST /v1/renders body. Only fields that differ from their defaults are shown. See the element field reference for every default.

Both id and duration are required on image elements. An empty or missing id causes the image to be silently skipped by the renderer. A missing duration produces a zero-length window. The API returns 422 for either omission.

Images and video both default to z_index: 0; text defaults to z_index: 1. When two elements share a z_index, array order breaks the tie — whichever is listed later in elements paints on top. A logo listed after the video is already above it with no z_index at all. Set an explicit z_index only when you need an order that does not match the array order; every declared ordering is preserved (the wire key is z_index × 1000 + array index).

Image over video

Logo centered on a video background. z_index: 1 places it above the video layer.

{
  "width": 1920,
  "height": 1080,
  "duration": 6,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 6
    },
    {
      "type": "image",
      "id": "logo1",
      "source_url": "https://cdn.example.com/logo.png",
      "duration": 6,
      "width": "30%",
      "height": "30%",
      "z_index": 1
    }
  ]
}

Crop

Crop 10% from each edge, placed over video.

{
  "width": 1920,
  "height": 1080,
  "duration": 6,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 6
    },
    {
      "type": "image",
      "id": "img1",
      "source_url": "https://cdn.example.com/photo.jpg",
      "duration": 6,
      "width": "80%",
      "height": "80%",
      "crop_top": 0.1,
      "crop_bottom": 0.1,
      "crop_left": 0.1,
      "crop_right": 0.1,
      "z_index": 1
    }
  ]
}

Border and rounded corners

{
  "width": 1920,
  "height": 1080,
  "duration": 6,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 6
    },
    {
      "type": "image",
      "id": "img1",
      "source_url": "https://cdn.example.com/photo.jpg",
      "duration": 6,
      "width": "60%",
      "height": "60%",
      "border_radius": 24,
      "border_color": "#ffffff",
      "border_width": 4,
      "z_index": 1
    }
  ]
}

border_radius, border_width, shadow_x, and shadow_y are pixel fields — a percentage string on any of them is a 422. border_radius also takes a per-corner object for asymmetric cards, e.g. a header rounded only on top:

{ "top_left": 24, "top_right": 24, "bottom_right": 0, "bottom_left": 0 }

The renderer normalizes the pixel value to a fraction of half the shorter side, so a value at or above half the shorter side gives a pill.

Drop shadow

shadow_x / shadow_y are pixels. shadow_blur is not — it is the renderer’s 0–100 blur-strength scale (0 = hard edge, 100 = maximum), clamped to that range. A shadow with shadow_x and shadow_y both 0 is a 422: the renderer skips the whole shadow pass at zero offset, so set at least 1px.

{
  "width": 1920,
  "height": 1080,
  "duration": 6,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 6
    },
    {
      "type": "image",
      "id": "img1",
      "source_url": "https://cdn.example.com/photo.jpg",
      "duration": 6,
      "width": "50%",
      "height": "50%",
      "shadow_color": "#000000",
      "shadow_blur": 20,
      "shadow_x": 8,
      "shadow_y": 8,
      "z_index": 1
    }
  ]
}

Effects, blends and mattes on images

Image elements take the same compositing vocabulary as video: the full effects chain, all 17 blend_mode values, backdrop_blur, and matte.

{
  "width": 1920,
  "height": 1080,
  "duration": 6,
  "elements": [
    {
      "type": "video",
      "id": "vid1",
      "source_url": "https://cdn.example.com/clip.mp4",
      "time": 0,
      "in_point": 0,
      "out_point": 6
    },
    {
      "type": "image",
      "id": "grain1",
      "source_url": "https://cdn.example.com/grain.png",
      "duration": 6,
      "blend_mode": "soft_light",
      "effects": [{ "type": "add_grain", "intensity": 40 }]
    }
  ]
}

lut_url / lut_intensity are the exception — they are accepted on an image element and then silently dropped. See Color Adjustments for what to grade a still with instead, and Effects Examples for the full effect catalog.

Get Started

Renders

Render Examples

Recipes

Tasks

Webhooks

SDKs

Image over video

Crop

Border and rounded corners

Drop shadow

Effects, blends and mattes on images

​Image over video

​Crop

​Border and rounded corners

​Drop shadow

​Effects, blends and mattes on images

Image over video

Crop

Border and rounded corners

Drop shadow

Effects, blends and mattes on images