compose_video_with_overlay concatenates files; it does not generate them

compose_video_with_overlay concatenates files you already have. It does not generate a clip. It does not trim a single source into a highlight (that is cut). It does not build a scored, captioned timeline (that is the editor). Point it at a prompt instead of URLs and there is nothing to merge.

Stitch multiple clips into one video is the named agent job. Photos, clips, or both — merged in the order you give them. Each image needs a hold duration. Each video may carry a trim range. Optionally, a picture-in-picture overlay sits on top of the whole concat. Required input is base_media. The fee is a flat per-video processing charge, shown before render, not a generative model.

That cheapness is the trap. People send it when they meant to generate, because it looks like "make me one video." It will make one video out of whatever you listed. If you listed nothing real, you get nothing real.

What the job is

Order. Duration. Optional overlay. A slideshow-style hold of stills, a sequence of generated takes, a photo then a clip then a photo. Concat in array order. Omit the overlay URL to just stitch the base.

If you only have one file and you want to keep ranges from it, trim or cut a video is cut_video. Stitch is for multiple sources (or images plus video). The notes on cut say so: ranges from multiple different source videos belong here.

If the "overlay" is the whole point and the base is a single video, overlay a talking head is the narrower UGC composite. Use stitch when the base is more than one item, when images mix with video, or when per-clip trims are part of the merge.

What it is not

• A generate. Text-to-video and image-to-video mint footage. Stitching empty hands does not mint footage.
• A full edit with music and captions. Build a video from clips, music, and captions is edit_video. Transitions, VO, caption layers, a 480p preview. Compose will not score the piece because you mentioned a song in the chat.
• A recurring series. Scheduling new scenes on a clock is a workflow job. Concatenating last week's exports is this job. They are easy to confuse in a sentence that starts with "put these together every Monday."
• Background removal. Keying a talking head is remove_background / the FFmpeg black-key path. Compose can then overlay the keyed file. It will not key for you unless you passed remove_black_background for a black overlay — and that is still not a green-screen model.

Generate first, or upload first. Stitch second. Reverse that order and you pay a compose on a list you then have to rebuild.

The test

Are all of the shots already URLs, in the order they should play, and the only remaining work is one file?

Yes: this job. List them. Set holds and trims. Confirm the processing fee.

If any shot does not exist, generate or cut that shot as its own named job. Then come back.

FAQ

Can I stitch clips that are still generating?

Not usefully. Compose needs URLs. Wait for the takes. Concatenating a half-ready list means paying twice.

Why not always use the full editor instead?

If you need music, captions, and a preview loop, use edit_video. If you need order and holds, stitch is the smaller bill. The expensive habit is the editor rebuild to change a sequence stitch would have done.

Does this replace a slideshow-to-video convert?

Turn a slideshow into a video starts from a saved slideshow id, with transition style and per-image duration. Stitch starts from an ad-hoc media list. Use the convert when the slideshow already exists as an object.

Can I generate missing shots inside the stitch call?

That is two jobs. The compose tool has no model picker for new footage. Name the generate, then name this.