Cyber Monday half-banner: price card over a clip, compose stack

Stack, not overlay

For a half-banner, call POST /v1/timeline-1.0/compose with operation: "stack", one still and one video. stack tiles two regions of one frame; the defaults are horizontal, still on top, ratio 0.5. Use overlay if the card should sit on top of the video instead. Cyber Monday 2026 is Monday, November 30.

The HTTP field for stack versus overlay is operation, not mode; mode is the async or sync communication option. Both media URLs must already be your workspace's media.sume.com artifacts or assets.

Request

curl -sS -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: cm-banner-001" \
  -d '{
    "operation": "stack",
    "image": { "url": "https://media.sume.com/artifacts/artf_demo/price-card.png" },
    "video": { "url": "https://media.sume.com/artifacts/artf_demo/product-clip.mp4" },
    "layout": { "split": "horizontal", "image_region": "top", "ratio": 0.3 },
    "output": { "width": 720, "height": 1280, "fps": 25 }
  }'

Layout keys

ratio is the still's share of the frame, from 0.1 to 0.9, and the video takes the exact remainder. The still is held for the whole clip and cannot lengthen it; the output length always comes from the video layer, to a ceiling of 300 seconds.

Errors and audio

Mixing stack and overlay keys returns 400 (compose_stack_takes_no_overlay_layout or compose_overlay_takes_no_stack_layout), and compose_image_region_wrong_axis fires when a region does not match the split. A mute video is a warning, not a failure. Set output.width and height to the timeline you will assemble into so the shot is not rescaled twice.