compose_video_with_overlay handles the case merge_movie_scenes doesn't: a mixed timeline of images AND videos, concatenated in the order you list them — plus, optionally, per-clip range trims so you can pick exactly which seconds of each video item to use without a separate cut_video pass first.
Each item in base_media is either an image (with a required duration_sec for how long it holds on screen) or a video (which can be trimmed via duration_sec, or a start_sec/end_sec range).
Powered by
MERGE/STITCH multiple media items (images, videos, or any mix) into a single final video, with an OPTIONAL picture-in-picture overlay video on top. PRIMARY use cases: (A) Merge user-uploaded images + an existing video into one video (e.g. user uploads photos and wants them stitched onto a clip). (B) Merge multiple videos with optional per-clip range trims (e.g. clip A seconds 3-8, then clip B seconds 0-5, then clip C). (C) Stitch a series of images each held on screen for a custom duration (slideshow-style). (D) Any of the above with a corner picture-in-picture overlay video composited on top. Each base item is { kind: 'image' | 'video', url, duration_sec?, start_sec?, end_sec? }. For 'image' items: duration_sec is REQUIRED (seconds the image stays on screen). start_sec / end_sec are ignored. For 'video' items you may EITHER pass duration_sec (trim from start to N seconds) OR pass start_sec + end_sec (keep the [start_sec, end_sec) range — both must be set together). If neither is set the video plays end-to-end. Items are concatenated in the array order. Omit overlay_video_url to just stitch the base. Use this INSTEAD of create_ugc_video_overlay whenever the base is more than a single video, when combining images with videos, or when you need per-clip range trims as part of the merge.
What to tell the agent
Versely's agent maps this plain-English request directly onto compose_video_with_overlay. You don't need to know the parameter names — just describe what you want.
“Combine these three photos (3 seconds each) with this video clip (seconds 5 to 10 only) into one video, in that order.”
How it works
1. List your items in order
base_media is an ordered array — items play in the order you list them, mixing images and videos freely.
2. Set image durations
For 'image' items, duration_sec is required — how many seconds that photo stays on screen.
3. Trim video items if needed
For 'video' items, either set duration_sec (trim from the start) or start_sec + end_sec together (keep a specific range) — leave both unset to play the whole clip.
4. Add an optional overlay
A picture-in-picture overlay_video_url can be layered on top of the whole composed base if you also want a talking-head or reaction clip in the corner.
What it costs
Billed as a standard compose operation, scaling with the number of items and total output length. Ask the agent for estimate_cost before running it on a long timeline.
The formula behind that number: What does editing a video cost if I keep changing it? — charges per finished export, so iteration is free and the count is the whole bill.
Limits & things to know
- For 'video' items, duration_sec and start_sec/end_sec are mutually exclusive approaches — don't mix both on the same item.
- This is a fixed-order concatenation, not a freeform multi-track timeline editor.
- If your base is a single video with no images mixed in, merge-videos (merge_movie_scenes) or trim-a-video (cut_video) are the simpler, more direct tools.
Who uses this
- Slideshow-style videos mixing photos and short clips
- Combining multiple source videos with precise per-clip trims in one pass
- Building a before/after or timeline-style sequence from mixed media
Frequently asked questions
Can I mix photos and video clips in the same output?+
Yes — that's exactly what compose_video_with_overlay is for. Each item in base_media can be an image or a video, played in the order you list them.
Can I trim each video clip differently as part of the merge?+
Yes — each video item accepts its own duration_sec (trim from the start) or start_sec/end_sec range, so you don't need a separate cut_video pass first.
Can I add a picture-in-picture overlay too?+
Yes — overlay_video_url layers an optional PiP video on top of the whole composed base, with position and size controls.
Related Versely tools
Related editing jobs
Combine Photos and Clips Into One Video inside Versely
The all-in-one AI studio for creators. 60+ models for video, image, voice, music and lipsync in a single app.