Overlay video_fit contain: keep a wide product clip uncropped

To keep a wide product clip from being cropped when you put a sale plate over it, set layout.video_fit to contain on a Sume timeline-1.0/compose request with operation: "overlay". contain fits the whole clip inside the output frame, while cover fills the frame and cuts the edges. The still, which is your plate, sits on top at the position you choose.

The layout keys are listed in Timeline compose (read 2026-10-06). For overlay, video_fit is the only fit key you may send, because image_fit belongs to stack. The job builds one MP4 and costs $0.02 flat.

Which layout keys does overlay accept?

Overlay keeps the plate small and the clip full. Stack keys such as split, image_region, and ratio are refused with compose_overlay_takes_no_stack_layout.

What does the request look like?

This request lays a sale plate across the bottom of a wide clip at 80 percent of the frame width, and keeps the clip uncropped. Both URLs must be this workspace's media.sume.com files, so import them first with POST /v1/media-imports.

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: sale-plate-wide-clip-001" \
  -d '{
    "operation": "overlay",
    "image": { "url": "https://media.sume.com/artifacts/artf_demo/sale-plate.png" },
    "video": { "url": "https://media.sume.com/artifacts/artf_demo/wide-product.mp4" },
    "layout": { "position": "bottom", "width_ratio": 0.8, "video_fit": "contain" },
    "output": { "width": 720, "height": 1280, "fps": 25 }
  }'

When should I choose cover instead?

Choose cover when the subject is centered and an edge crop costs you nothing. Choose contain when the product runs to the edge of the frame, or when the plate must not hide part of a cropped label. If the clip should be a vertical frame with no empty space, crop the source first with video filter and then compose.

• The output length comes from the video layer, and the still never makes the clip longer.
• Set output.width and output.height to your timeline size, so the shot is not rescaled again later.
• Read the job through GET /v1/jobs/:id/result, which returns kind: timeline_compose with video_url.