Half-banner video: a still stacked over a clip for $0.02

To put a banner image above a video, call POST /v1/timeline-1.0/compose with operation: "stack". The job costs a flat $0.02, the output length comes from the video layer, and the ceiling is 300 seconds (Timeline compose).

Request

The defaults are horizontal split, still on top, ratio 0.5. Here the still takes 30% and the video the remainder, at 720x1280.

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: halfbanner-001" \
  -d '{
    "operation": "stack",
    "image": {"url": "https://media.sume.com/artifacts/artf_demo/banner.png"},
    "video": {"url": "https://media.sume.com/artifacts/artf_demo/talk.mp4", "duration": 20},
    "layout": {"split": "horizontal", "image_region": "top", "ratio": 0.3},
    "output": {"width": 720, "height": 1280}
  }'

Stack vs overlay

Gotchas

• The still never lengthens the clip; it holds for the whole video layer.
• A mute video is a warning (compose_video_has_no_audio), not a failure.
• Mixing stack and overlay keys is a 400. left/right on a horizontal split gives compose_image_region_wrong_axis.
• Feed the output to Timeline 1.0 video[]; set output.width/height to the target to avoid a second rescale.

Worked example: the 30% banner

With ratio: 0.3 on a 720x1280 output the still takes 30% of the height, 384 px, and the video gets the exact remainder, 896 px. The default ratio of 0.5 would split it 640 and 640. The price is the same $0.02 whether the clip is 5 or 300 seconds, because the rate is flat per job.

The default output is 1080x1920 at the frame rate of the video layer. Set output.width and output.height to the timeline you assemble into so the shot is not rescaled a second time. Both the still and the video URL must be media.sume.com artifacts or assets of your workspace; import other files first, or you get unsupported_media_source.