Bulk add a watermark to videos: same logo, every file

To bulk add a watermark to videos, apply one fixed overlay (the same logo image, size, and position) to every video in the set, one output file per video. By API that is a loop: one overlay job per video with identical settings, and a new watermarked file back for each.

On Sume the overlay job is Timeline compose with operation: "overlay". The facts below come from the Timeline compose docs, read on 2026-09-29. For one video and the full list of layout keys, see How to add a logo or watermark to a video.

How do I watermark many videos in one run?

Fix the logo and the layout once, then loop over the videos. Each call sends the same image.url and layout, the video's own video.url, and an Idempotency-Key derived from that video, so a retried request never makes a second job. Both URLs must be files in your Sume workspace on media.sume.com, such as earlier Sume outputs; off-host URLs are rejected.

import os, requests

API = "https://api.sume.com/v1/timeline-1.0/compose"
KEY = os.environ["SUME_API_KEY"]
LOGO = "https://media.sume.com/artifacts/artf_demo/logo.png"
LAYOUT = {"position": "bottom", "width_ratio": 0.2, "margin_ratio": 0.04}

videos = {  # your id -> (Sume-hosted video, its width, its height)
    "ep-01": ("https://media.sume.com/artifacts/artf_demo/ep01.mp4", 1080, 1920),
    "ep-02": ("https://media.sume.com/artifacts/artf_demo/ep02.mp4", 1920, 1080),
}

for vid, (url, w, h) in videos.items():
    r = requests.post(API, json={
        "operation": "overlay",
        "image": {"url": LOGO},
        "video": {"url": url},
        "layout": LAYOUT,
        "output": {"width": w, "height": h},
        "webhook_url": "https://example.com/hooks/sume",
    }, headers={"Authorization": f"Bearer {KEY}",
                "Idempotency-Key": f"watermark-v1-{vid}"})
    r.raise_for_status()

How do I keep the watermark identical across videos?

Keep image.url and layout constant, and watch the frame size. width_ratio is a share of the frame's width (0.05 to 1), so the same ratio draws a smaller logo on a portrait frame than on a landscape one. margin_ratio (0 to 0.45) is a share of the height. If your set mixes shapes, batch each shape with its own ratio.

• Set output.width and output.height to each video's size. The default output is 1080×1920, so a landscape video left on the default is reframed to portrait.
• Render one video, check it, then run the rest. Change the key prefix (watermark-v2-…) when you change the layout, because one key belongs to one exact request.

How much does it cost to watermark videos in bulk?

One compose job per video reserves up to $0.02 per job and captures its own compute, never above that, so the total scales with the number of videos, not their length. Add the 5.5% agent fee by default.

Large batches queue: jobs past your workspace's concurrency limit wait as queued, and a submit past the queue capacity gets 429 queue_full. Batch video processing covers pacing the loop.

What can't a bulk watermark do?

• Show the logo for only part of a video, or move it: the still covers the whole clip in one place.
• Watermark a video longer than 300 seconds in one job: that is the compose ceiling. Each output is as long as its video and keeps the video's sound; the one-video guide covers length, sound, and placement.
• Take your own files, the logo included, from a computer or a public URL: compose reads only Sume-hosted media.
• Stamp two marks in one job: one job takes one still, so a second mark is a second compose on the first result.