One timeline call or a chain of edit tools

A six-clip cut done as trim, then attach audio, then burn captions is three round trips and two intermediate files. Attach and captions each take a credit charge, and none of those tools has a preview pass. The same finished video as one edit_video call is one round trip, a 480p preview you can iterate on (free, with a short per-user cooldown), and one export charge. The chain is the wrong default whenever you actually want a single timeline.

edit_video is an EDL render: an ordered list of clips plus optional transitions, text overlays, music, voiceover, overlay, captions, aspect ratio, and resolution, stitched into one file. Its own tool description prefers it over chaining cut_video, attach_audio_to_video, and an add_*_captions tool for a multi-clip assembly in a single step.

The chain still earns its keep. Knowing which job is which is the skill.

What each round trip actually costs you

Every standalone edit tool takes a hosted URL, writes a new hosted URL, and returns. That is a feature when the new file is a product you will reuse. It is overhead when the new file is only a stepping stone to the next tool.

Job	Tool	What you get back	What you pay
Trim, cut out a middle, or keep several ranges of one file	cut_video	A new video of the kept ranges	No credit charge on the current path
Swap or mix a soundtrack	attach_audio_to_video	The same pictures with new audio	A flat credit fee, independent of length
Burn speech captions	add_veed_captions	A captioned copy	Its own captioning charge
Burn a fixed text overlay (not a transcript)	add_video_captions	An overlaid copy	Its own overlay charge
Stitch several videos with a shared transition	merge_movie_scenes	One concatenated video	No credit charge on the current path
Mix images and clips, optional per-clip trims, optional PiP	compose_video_with_overlay	One concatenated video	A credit charge
Full assembly: clips + layers + format	edit_video	One finished video	Free 480p preview with a short per-user cooldown; one editor_export charge on the final

Three things fall out of that table.

First, the chain creates intermediates. Clip A trimmed becomes URL 2, then URL 3 with music, then URL 4 with captions. A caption timing fix re-runs the caption tool on URL 3, if you still have it. Lose the intermediate and you rebuild from URL 2, or from A.

Second, the chain has no preview pass. The free 480p render with a short per-user cooldown lives on edit_video (preview: true). cut_video has no preview flag. attach_audio_to_video and the caption tools charge when they run. If you are still deciding whether the music bed is too loud, paying for a mix, then paying again to remix, is the expensive way to find out.

Third, assembly complexity does not multiply the editor export. A two-clip trim and a dense cut with music, overlay text, and a caption track are both one editor_export when they go out as one edit_video final. The preview-versus-export billing is a count of finished files, not a count of layers.

When the single timeline call wins

Use edit_video when the output is one video and the inputs are layers of that video.

Typical asks that belong here:

• "Stitch these four clips, crossfade, put this track underneath, burn captions, export 9:16."
• "Same edit, but swap the third clip and make the title card shorter."
• "Preview that at 480p before I pay for the export. Space it from the last preview."

Those are one description, re-rendered. The one-pass assembly is the task page; asking the agent to build a video from clips, music, and captions is the chat phrasing.

The preview loop is why the timeline wins while the cut is still moving. Set preview: true, watch the 480p pass (the free preview carries a short per-user cooldown, so do not hammer it), change a trim or a caption, preview again. Credits stay at zero until you omit preview or set it false.

Saved drafts compound that. save_editor_project stores the EDL as project state, not as a baked MP4. Next week you load the draft, swap the footage URLs, preview, export once. That is the reusable draft pattern.

A prompt that lands in the right place:

Assemble these four HTTPS clips in this order, 0.4s crossfade, this music mixed under the original audio, captions in the glass style, 9:16. Render a 480p preview first. Do not export until I confirm.

That is one edit_video call with preview: true. After notes:

Swap clip 3 for this URL, pull the title off at 2.5s, preview again.

Still one call. Then:

Export the final.

That is the charged render.

When the chain wins

The timeline is the wrong tool when you do not want a new assembly. You want a surgical transform of one file, and you want that transform's output to exist on its own.

Audio-only changes on a finished picture. attach_audio_to_video copies the video stream losslessly. It does not re-encode the pictures. edit_video re-renders the timeline. If the cut is already right and you are replacing a scratch voiceover or mixing a bed under existing dialogue, attach the audio as its own step. Use replace when the supplied track should be the only audible thing; use mix with separate music_volume and original_volume when dialogue has to stay.

A trim you will reuse as a master. Cutting ranges out of one source with cut_video gives you a kept-range file you can drop into several later jobs: a Shorts cutdown, a feed crop, a captioned variant. Baking that trim only inside an EDL means you re-trim every time. Segments are keep ranges, not delete ranges. One segment trims. Two skip a middle. N stitch kept pieces in order.

Captioning a video that is otherwise done. Speech captions transcribe what is on the file. They do not need the rest of the EDL. Auto-transcribe and caption is the right call when the pictures and the soundtrack are already locked. preview_caption_style can render the first few seconds in a candidate look before you spend the full caption charge. Rebuilding the whole timeline just to change the preset is wasted work.

A merge that is only a concat. If you have three complete scene files and you want them joined with one transition style and one audio-handling rule, merge_movie_scenes is the direct tool. If the list mixes stills and clips, or each clip needs its own in/out, compose_video_with_overlay is the direct tool. Both are assembly, but they are narrower than a full EDL, and they do not pretend to be a timeline editor.

A prompt that should stay a chain:

Trim this video to 5–18s and give me that file. Then mix this music under the original voice, music quieter. Do not rebuild a timeline.

Two tools, two outputs, and the trimmed master remains available.

A rule you can actually apply

Ask one question: is the next output a layer of the same video, or a new asset?

• Layer of the same video (order, trims, transitions, on-screen text, music, voiceover, overlay, captions, output ratio): one edit_video call. Preview at 480p with the per-user cooldown in mind; export once.
• New asset (a kept-range master, a lossless audio swap, a captioned copy of a locked cut, isolated vocals, extracted frames): the matching standalone tool. Feed that URL into the timeline later if you still need an assembly.

The hybrid that works in production is utilities first, timeline last. Isolate a vocal, generate a voiceover, extract a thumbnail frame, trim a long interview down to the usable ranges. Those are products. Then one EDL consumes those URLs and renders the piece you will publish.

The hybrid that wastes credits is timeline-shaped work done as a chain: cut, then attach, then caption, each writing a file you throw away. Attach and captions still bill, those tools have no 480p preview pass (free, short per-user cooldown), and a late caption change has no timeline to rewind.

Clips still have to be HTTPS URLs from your workspace or a prior generation. Local paths fail before any of this matters.

FAQ

Does a more complex timeline cost more credits to export?

No. The final edit_video render (preview: false, the default if you omit the flag) is one editor_export charge regardless of clip count, overlays, and caption tracks. What multiplies the bill is how many times you export, plus billed standalone tools (attach, captions, compose) chained as if they were one edit.

Can I preview a chained cut or audio attach the same way?

No. The free 480p pass with a short per-user cooldown is a parameter on edit_video. cut_video has no preview flag. attach_audio_to_video and the caption tools charge when they run. If you are still iterating on pacing, music, and captions together, put them on one timeline and preview there.

If I already captioned a clip, should I rebuild it inside edit_video?

Only if you also need other timeline work (a new trim, a new clip order, a new overlay). If the pictures and audio are locked and you want a different caption look, run the caption tool on that file. If you want a new assembly that happens to include captions, describe the whole edit in one edit_video call and do not pre-caption the sources.

Is merge_movie_scenes the same thing as edit_video?

No. merge_movie_scenes concatenates videos with a shared transition and audio-handling setting. edit_video is the editor pipeline: trims, speed, texts, music, voiceover, overlay, captions, aspect ratio, resolution, and the preview/export split. Use merge when you only need a concat. Use the timeline when you need layers.

Pick the timeline when the result is one video with several layers. Pick the chain when each step has to survive as its own file.