Headphones listing video: spec card on the left, clip on the right

To put a spec card beside a product clip in a 16:9 video, call POST /v1/timeline-1.0/compose with operation: stack, layout.split: vertical, image_region: left and a ratio for the card's share of the width, plus output of 1920 by 1080. The job is $0.02 flat. A 0.35 ratio gives the card 35% of the width and the clip the other 65%.

A headphones listing is a landscape-page problem. Product pages, marketplace listing galleries and the first screen on a laptop all show wide video, and a spec card (drivers, battery life, weight) is what a buyer wants to read while the product turns.

The finished shot goes into a Timeline render like any other clip. Compose is only the shot-building step, and the sequence, transitions and audio spine stay on the Timeline, which keeps each job small and cheap to redo.

Vertical split

The default compose layout is the half banner: horizontal split with the still on top at 0.5. Switch to a side-by-side with split: vertical and pick image_region: left or right. Pairing the wrong region with the split, such as left on a horizontal split, returns compose_image_region_wrong_axis, which is the single most common error in this API.

ratio is the still's share of the frame from 0.1 to 0.9, and the video takes exactly the remainder. image_fit and video_fit take cover, contain or stretch; blur is not a compose fit. Use contain for the card so none of the text is cropped, and cover for the clip.

Output size and audio

The compose output uses the clip's own audio and its frame rate. If you do not pass output, it defaults to 1080 by 1920, so for a landscape card set output.width to 1920 and output.height to 1080 (even integers 256 to 2160 are accepted). Set the same size on the Timeline render later so the shot is not rescaled twice.

Compose length always comes from the video layer. A card that is a still stays up for the entire clip, and the ceiling is 300 seconds. If you ask for more than the clip has, the job clamps with compose_duration_clamped_to_source and still succeeds.

Design the card at the pixel size it will occupy, 672 by 1080 for the 0.35 ratio, so the text is crisp. The text on the card is only as accurate as you make it: take battery hours and weight from your product sheet rather than from anything the video model rendered.

Because the card is a still, it is also easy to localise: design one card per language, run the same compose with a different image.url, and keep the clip identical. Each language is another $0.02 shot rather than another full video edit.

A side-by-side shot

import os
import uuid
import requests

body = {
    "operation": "stack",
    "image": {"url": os.environ["SPEC_CARD_URL"]},
    "video": {"url": os.environ["HEADPHONES_URL"], "duration": 12},
    "layout": {"split": "vertical", "image_region": "left", "ratio": 0.35,
               "image_fit": "contain", "video_fit": "cover"},
    "output": {"width": 1920, "height": 1080},
}
r = requests.post(
    "https://api.sume.com/v1/timeline-1.0/compose",
    headers={"Authorization": f"Bearer {os.environ['SUME_API_KEY']}",
             "Idempotency-Key": f"hp-{uuid.uuid4()}"},
    json=body, timeout=60)
print(r.status_code, r.json().get("request_id"))

Three shots, one video

Poll the job and read video_url, a new artifact. A small listing set might use three shots, such as the card with the turning product, a card with the case, and a card with the colours, each its own compose at $0.02. Join them with a Timeline render at $0.10 for a 30-second video, so the whole thing is $0.16 on the same rates.

The same recipe works with the card on the right (image_region: right), which suits right-to-left reading layouts or a page where the product image sits beside a left-aligned column of text. Try the two on one clip before you batch a catalogue; each test is another $0.02 and keeps the decision with you.

Mixing stack and overlay keys is refused (compose_stack_takes_no_overlay_layout), so keep position, width_ratio and margin_ratio out of this request. For the horizontal, top-and-bottom version see the half-banner price card post, and for the error codes see the compose errors post.