Add an image over a video: position, width_ratio, margin_ratio

In Sume's overlay compose, three keys place the still: position (top, center or bottom), width_ratio (0.05 to 1 of the frame width, default 0.9) and margin_ratio (0 to 0.45 of the frame height, default 0.05). The plate keeps its aspect ratio.

The table is from the Timeline compose docs, read 2026-10-01. Runway's changelog covers its editor panel; this is the API route to a similar still-on-video shot.

What do the three keys do?

They exist only on overlay; on a stack they are illegal.

What do the ratios come to in pixels?

The default output is 1080 by 1920. On that frame the default width_ratio of 0.9 is 972 pixels wide, and the default margin_ratio of 0.05 is 96 pixels of height. The sample below, 0.6 and 0.08, is 648 pixels and about 154 pixels. The plate keeps its aspect, so its height follows from the width; this is arithmetic, not a measured render.

How do I place a banner at the bottom?

Choose position: "bottom", set a width and give it some margin so it clears the frame edge. Only video_fit applies on an overlay.

curl -X POST https://api.sume.com/v1/timeline-1.0/compose \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: compose-overlay-001" \
  -d '{
    "operation": "overlay",
    "image": { "url": "https://media.sume.com/artifacts/artf_demo/logo.png" },
    "video": { "url": "https://media.sume.com/artifacts/artf_demo/talk.mp4" },
    "layout": { "position": "bottom", "width_ratio": 0.6, "margin_ratio": 0.08 }
  }'

What if I send stack keys too?

The request is a 400: compose_overlay_takes_no_stack_layout. For the stack vocabulary, see stack an image over a video.