App Promo Half-Banner: A Headline Still Over a Screen Recording

The short answer

Timeline compose puts one still and one video on screen at the same time and returns one MP4 for $0.02 flat per job (docs read 2026-10-09). With operation: stack and the default layout, the still is on top and the video below, which the docs call the half-banner (the Korean ad term is 반배너). Set layout.ratio for the still's share of the frame, from 0.1 to 0.9, and output to the final size so the shot is not rescaled twice.

Stack or overlay

Stack tiles two regions of a frame. Overlay lays the video as a plate over the still, with position (top, center, bottom), width_ratio (0.05 to 1, default 0.9) and margin_ratio (0 to 0.45 of the height). Overlay suits a phone-shaped screen recording floating over a brand color, and stack suits a headline strip above the product. Mixing the two vocabularies in one request returns a 400.

A request

Both URLs must already be this workspace's media.sume.com artifacts or assets, so import the headline image and the recording first with POST /v1/media-imports. Send an Idempotency-Key. The image must probe as a still and the video as video, or you get compose_image_not_still or compose_video_not_video.

The output keeps the audio of the video. A silent screen recording only gives the warning compose_video_has_no_audio, and the clip still renders. Add the voiceover later in a Timeline 1.0 render, where the compose MP4 goes into a video[] slot.

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

Where it fits

Use it for app-store style promos, tutorial teasers and feature highlights, where one line of text must stay on screen while the product moves. Make the headline image with an image model at a size close to the strip, for example 1080 by 672 for a 0.35 share of a 1920 high frame (1920 x 0.35 = 672). For a pixel pass such as dimming the recording behind text, use video filter first at $0.02 per job.

Check the result on a phone before you ship. The top strip is where platform interface elements often sit, so keep the headline inside a margin and test it on the platform's preview. A 0.35 ratio on a 1280-pixel-high output gives a still region of 448 pixels (1280 x 0.35) and a video region of 832 pixels, so a 9:16 recording will be letterboxed or cropped by its video_fit. Choose cover to fill and crop, or contain to keep the whole screen visible; blur is not available in compose.