Pin a product card on a live-selling clip with one overlay call

To pin a product card on a live-selling clip, send POST /v1/timeline-1.0/compose with operation: "overlay", the card as image.url, the clip as video.url, and a layout of position, width_ratio and margin_ratio. It costs $0.02 per job at the documented public rate, and the card stays for the whole clip.

This is for a still card, such as a product photo with a name and price you made elsewhere. Compose does not write the card for you and does not time it to a moment in the pitch; it holds the still for the full clip you hand it.

What goes in the request?

Required fields are operation, image.url and video.url. Both URLs must already be this workspace's media.sume.com artifacts or assets; there is no open-internet fetch, so import first with POST /v1/media-imports. The image must probe as a still and the video as video, or the job is refused. Idempotency-Key is required.

Output length always comes from the video layer: video.duration if given, otherwise the rest of the file from video.source_in. The still can never lengthen the clip. The ceiling is 300 seconds, so a long replay needs a source_in and duration window around the pitch you want to carry the card.

A practical order for a live replay is to trim the pitch first, then compose, so the overlay job only touches the seconds you will publish. Trim costs $0.02 per job and compose costs $0.02 per job, so a trimmed, carded clip is two small jobs.

How do you place the card?

Overlay uses three layout keys. position is top, center or bottom. width_ratio runs 0.05 to 1 of the frame width, default 0.9, and the card keeps its own aspect ratio. margin_ratio runs 0 to 0.45 of the frame height, default 0.05.

Do not mix in the stack vocabulary (split, image_region, ratio). The API refuses that with compose_overlay_takes_no_stack_layout. If you want the still beside or above the clip instead of on top of it, that is stack, covered in put a still above a video.

What does a sync call look like?

The script below overlays a card across the first 45 seconds of a pitch at the bottom, 80 percent of the width, and requests mode: "sync". Sync waits up to 30 seconds and returns a finished job, or a 202 you poll. The result is kind: timeline_compose with a new video_url and duration_seconds.

Audio passes through from the video. A mute video only raises the compose_video_has_no_audio warning, so the job still succeeds.

import json, os, urllib.request

KEY = os.environ["SUME_API_KEY"]
body = {
    "operation": "overlay",
    "image": {"url": "https://media.sume.com/artifacts/demo/card.png"},
    "video": {"url": "https://media.sume.com/artifacts/demo/pitch.mp4",
              "source_in": 0, "duration": 45},
    "layout": {"position": "bottom", "width_ratio": 0.8,
               "margin_ratio": 0.08},
    "output": {"width": 1080, "height": 1920, "fps": 30},
    "mode": "sync",
}
req = urllib.request.Request(
    "https://api.sume.com/v1/timeline-1.0/compose",
    json.dumps(body).encode(),
    {"Authorization": f"Bearer {KEY}",
     "Content-Type": "application/json",
     "Idempotency-Key": "pitch-card-001"})
with urllib.request.urlopen(req) as r:
    print(r.status, json.load(r))

What should you do with the result?

The composed MP4 is an ordinary Sume-hosted file, so drop it into a Timeline 1.0 video[] slot to join it with other clips, or into a highlight reel built on source_in. Set output.width and output.height to the timeline you assemble into so the shot is not rescaled twice.

One limit to plan for: the card is a single static image for the entire clip. If a price or product changes mid-pitch, cut the pitch at that point with video trim and compose one card per piece.

Check the finished clip by eye before you publish: confirm the card does not cover the host's face or on-screen text, and nudge position or width_ratio if it does.