Put a logo or lower third over a talking avatar video with compose

Use POST /v1/timeline-1.0/compose with operation 'overlay'. It puts one Sume-hosted still, such as a logo plate or a lower-third graphic, over a video, and you choose position top, center or bottom. It costs $0.02 flat per job.

What overlay does

Compose takes one still and one video and returns one MP4 with both on screen. In overlay the still sits on top of the video for the whole clip. The output length comes from the video layer, and the still can never make the clip longer.

Both URLs must already be on media.sume.com for your workspace, so import files first with POST /v1/media-imports. An Idempotency-Key header is required.

Layout keys for overlay

Mixing stack keys with overlay keys returns 400 (compose_overlay_takes_no_stack_layout), so send only these.

A lower third

A lower third wants a wide, short plate near the bottom edge. Make the PNG with transparency, import it, and then send this.

import json, os, urllib.request

body = {
    "operation": "overlay",
    "image": {"url": os.environ["PLATE_URL"]},
    "video": {"url": os.environ["CLIP_URL"]},
    "layout": {"position": "bottom", "width_ratio": 0.8, "margin_ratio": 0.06},
    "mode": "sync",
}
req = urllib.request.Request(
    "https://api.sume.com/v1/timeline-1.0/compose",
    data=json.dumps(body).encode(),
    method="POST",
    headers={
        "Authorization": f"Bearer {os.environ['SUME_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "lower-third-001",
    },
)
with urllib.request.urlopen(req, timeout=40) as r:
    print(r.status)

Things to know

• A mute video returns a warning, compose_video_has_no_audio, not a failure.
• A video.duration past the end of the file is clamped with a warning.
• Default output is 1080 by 1920; set output.width and output.height to match your timeline so the shot is not rescaled twice.
• The overlay is a still, so it does not animate.

Cost

Branding ten avatar clips costs 10 x $0.02 = $0.20 in compose jobs. If a logo changes, re-compose from the clean clip; you do not need a new avatar render, which at plus quality would be $0.245 per second.

What to do

Keep the clean avatar clip and the plate as separate assets. That way a rebrand is a $0.02 job rather than a new render.