How to add an image to a video at a specific time

To add an image to a video at a specific time, show the picture only between two timestamps, either on top of the footage (an overlay) or in place of it (a cutaway), and leave the rest of the video as it was. With Sume, when the clip and the image are already hosted on Sume, compose the image over just that stretch of the clip with Timeline compose, then put the pieces back in order in one Timeline 1.0 render over the clip's detached audio.

The facts come from Sume's Timeline compose, Timeline 1.0, and Audio detach docs and the field descriptions in the Sume API reference, read on 2026-09-27. Anything described as current behavior is read from Sume's code.

How do I overlay an image for a few seconds?

Say the picture should float over seconds 5 to 9 of a 20-second, 1920×1080 clip. Both files must already be your workspace's media.sume.com artifacts or assets, such as earlier Sume job outputs. Sume has no public upload route for a file on your computer: its asset upload routes are hidden from the public API reference (which URLs each endpoint accepts). It takes three calls:

• POST /v1/audio-detach on the clip returns its sound as a wav. In the current compiler a render's sound comes only from its spine and an optional soundtrack, so this is how the clip keeps its audio.
• POST /v1/timeline-1.0/compose with operation: "overlay", the image, and the clip with video.source_in: 5 and video.duration: 4 returns a 4-second MP4 of that stretch with the image on top. Set output to the clip's size, because the default is 1080×1920.
• POST /v1/timeline-1.0/render lays three slots over the wav: the clip up to 5 s, the composed shot, and the clip again from source_in: 9.

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: overlay-5s-001" \
  -d '{
    "operation": "overlay",
    "image": { "url": "https://media.sume.com/artifacts/artf_demo/badge.png" },
    "video": { "url": "https://media.sume.com/artifacts/artf_demo/clip.mp4", "source_in": 5, "duration": 4 },
    "layout": { "position": "bottom", "width_ratio": 0.4 },
    "output": { "width": 1920, "height": 1080 }
  }'

How do I put the pieces back together?

Read the composed shot's video_url from GET /v1/jobs/:id/result, then render. The slots sit end to end on the detached wav, so the sound plays straight through, and the image appears at 5 s because the docs treat each slot's declared start as authoritative:

• Use hard cuts here, with no transition, so the three pieces meet where the clip was split.
• The unbilled POST /v1/timeline-1.0/plan checks the render body before you pay for it.

curl -X POST https://api.sume.com/v1/timeline-1.0/render \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: overlay-5s-render-001" \
  -d '{
    "audio": { "url": "https://media.sume.com/artifacts/artf_demo/clip.wav", "duration_seconds": 20 },
    "output": { "width": 1920, "height": 1080 },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4", "start": 0, "duration": 5 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/overlay-5s.mp4", "start": 5, "duration": 4 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4", "start": 9, "duration": 11, "source_in": 9 }
    ]
  }'

Where on the frame does the image go?

An overlay floats the still over the full-frame video as a plate that keeps its own aspect ratio. The plate is always centered horizontally, so there is no corner position: layout.position pins it top (the default), center, or bottom, and layout.width_ratio sets its width as a fraction of the frame (default 0.9). To split the frame between image and video instead, use operation: "stack", which tiles the two into separate regions of one frame. For an image over a whole clip of up to 300 seconds, one compose call is enough; add a logo or watermark to a video covers that case and every overlay key.

How do I insert an image in place of the footage?

Skip compose and give the still its own slot. Stills are static holds, so a still slot at start: 5 with duration: 4 replaces seconds 5 to 9 with the picture while the sound plays on, and the clip resumes at source_in: 9 as before. In the current code, the default fit, cover, crops a picture whose shape does not match the frame, while contain scales it to fit and pads with black. Add B-roll to a talking-head video uses the same pattern for cutaways.

What does it cost, and what are the limits?

Each step bills on its own, plus a 5.5% agent fee by default. Detach and compose are billed per job, with rates in GET /v1/catalog. The render reserves $0.10 per output minute on API pricing, counted as ceil(audio.duration_seconds / 60) minutes, and never charges more than its reservation, so the 20-second example reserves one minute.

• A composed stretch lasts at most 300 seconds. Its length always comes from the video layer, and the still can never lengthen it.
• The image must probe as a still (compose_image_not_still) and the clip as a video (compose_video_not_video).
• A render outputs 1 to 1,800 seconds from 1–200 slots, so one render can hold several timed images.
• One detach writes at most 900 seconds of audio, so for a longer clip detach two ranges and pass both files as audio.parts[].