How to add a logo or watermark to a video

To add a logo or watermark to a video, lay the logo image over every frame at a fixed size and place, then re-encode the clip. With Sume, both files must already be Sume-hosted, such as earlier Sume outputs; send the logo still and the video to POST /v1/timeline-1.0/compose with operation: "overlay". Sume scales the logo to width_ratio of the frame's width, keeps its shape, pins it at the top, center, or bottom, holds it for the whole clip, and returns one new MP4 with the clip's sound.

The details come from the Timeline compose docs and the compose schema in the Sume API reference, read on 2026-09-27. An animated logo or an end card is a different job, covered in logo animation.

How do I overlay a logo on a video?

Send operation, image.url, and video.url, which are all required, with an Idempotency-Key header. Both URLs must be media.sume.com files in your workspace, since off-host URLs are rejected; the image must be a still (compose_image_not_still otherwise) and the video a video. Sume's media URL rules cover which URL each endpoint takes.

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: logo-overlay-001" \
  -d '{
    "operation": "overlay",
    "image": { "url": "https://media.sume.com/artifacts/artf_demo/logo.png" },
    "video": { "url": "https://media.sume.com/artifacts/artf_demo/clip.mp4" },
    "layout": { "position": "top", "width_ratio": 0.2, "margin_ratio": 0.04 },
    "output": { "width": 1080, "height": 1920 }
  }'

How do I set the logo's size and position?

Four layout keys apply to an overlay. The default width_ratio of 0.9 spans most of the frame, so set it lower for a logo.

• Stack keys (split, image_region, ratio, image_fit) sent with an overlay are a 400, compose_overlay_takes_no_stack_layout.
• Set output.width and output.height (256 to 2160 each) to the clip's own size. The default output is 1080×1920 at the video's frame rate, so a landscape clip left on the defaults is reframed to portrait. A free probe with video inspect reports the size.

What happens to the video's length and sound?

The length always comes from the video: video.duration, or else the rest of the file from video.source_in. The logo is held for the whole clip and can never lengthen it, and the ceiling is 300 seconds. The clip's audio passes through; a mute video only warns compose_video_has_no_audio.

There is no compose GET route. Poll GET /v1/jobs/:id/status, then GET /v1/jobs/:id/result returns kind: timeline_compose with the new video_url and duration_seconds. Compose bills a flat amount per job, listed on the Timeline compose page; the docs say to confirm it live in GET /v1/catalog.

What can't a compose overlay do?

• Corners: the logo is always centered horizontally, so it sits top center, center, or bottom center.
• Opacity or motion: the layout keys above are the only overlay settings, and the still is held for the whole clip.
• Transparency is not documented: the docs don't say whether a PNG's transparent areas stay transparent, so check one test render before a batch.
• Two marks at once: one job takes one still. For a second mark, run another compose on the first job's video_url.
• The video filter is no substitute: it reads one clip, and filters that read a file, such as movie, are not on its allowlist.