The features endpoints as standalone utilities

The editor is one consumer of Versely's media utilities, not the owner of them. Frame extraction, merging, audio attachment, vocal isolation, and captioning each exist as their own job: one hosted input, one hosted output, usable from the agent, from MCP, or from the REST /api/v1/features surface. If you only ever meet them as checkboxes on a timeline, you will rebuild a whole EDL for work that is a single transform.

That habit is expensive in round trips and messy in intermediates. It is also unnecessary. The utilities were built to be called on their own.

The jobs that do not need a timeline

These are the ones operators reach for as pipeline steps. Each one is a real agent tool wrapping a features-style job.

Job	Agent tool	Input	Output	When it is the whole job
Pull stills	extract_video_frames	A video URL, optional time range, count, fps, format	Image URLs	Thumbnails, first-frame references, identity lock between shots
Concatenate videos	merge_movie_scenes	A list of video URLs, transition, audio handling	One video	Scene files that are already finished, joined in order
Mix or replace sound	attach_audio_to_video	Video URL + audio URL, replace or mix	One video	A locked picture that needs a new bed or VO
Pull vocals out of a mix	isolate_audio	An audio URL	A vocal-only track	Cleaning a recording before you attach it or transcribe it
Burn speech captions	add_veed_captions (and related caption tools)	A video that contains speech, a preset	A captioned video	The cut is done; you need subtitles on that file

Related jobs live on the same shelf even if you came here for those five: colorize_photo for a grayscale still, cut_video for keep-range trims on one file, compose_video_with_overlay when the concat mixes images and clips or needs per-item in/out points, preview_caption_style when you want the first few seconds of your video in a candidate caption look before paying for the full burn-in.

None of these require edit_video. None of them offer the editor's free 480p preview with its short per-user cooldown. Attach, isolate, and captioning bill when they run; isolation and captioning are duration-based (dynamic caption presets at 2× the basic rate). Frame extraction and merging are file transforms on hosted URLs, not a preview pass. That is the trade: one job, no timeline.

Five utilities, used as utilities

Frame extraction. Extract frames from a video when you need a still, not a new clip. A thumbnail, a reference image for the next generation, a first frame so shot 2 matches shot 1. Pass video_url and, if you know it, start_time / end_time as HH:MM:SS, plus frame_count. The stills come back as image URLs you can feed into image-to-image or image-to-video. Re-rendering an editor preview of the whole timeline just to screenshot a frame in a player is the long way around.

Merging. Stitch clips when the sources are already the right length and you want one file. merge_movie_scenes is video-only, with a shared transition_type, transition_duration, and audio_handling. compose_video_with_overlay is the mixed case: images with duration_sec, videos with optional start_sec/end_sec, optional corner overlay. Reach for edit_video instead when you also need captions, music, text overlays, and a preview/export loop on the same call.

Audio attach. Add music or a voiceover when the pictures are done. Two modes, and picking the wrong one is the usual defect: replace strips the original soundtrack (the default); mix keeps it and layers the new track with music_volume and original_volume. The video stream is copied losslessly. That is why this utility beats rebuilding the timeline for an audio-only change: you do not re-encode the pictures. Generate the track or the VO first if you do not already have one, then attach. Inputs need to be hosted URLs the server can fetch; file:// paths are rejected.

Isolation. Isolate vocals from a mixed recording when you want a dry voice and the bed is in the way. isolate_audio takes any audio URL. It is not the same tool as separate_music_vocals, which splits a Suno-generated track by taskId and audioId. If you point isolation at a generated song that still has its Suno ids, use the stem tool; if you point it at a field recording or a downloaded mix, use isolate_audio. That is the same split as stem separation versus pulling a voice out of a mix. Isolated vocals are a new asset. Attach them, transcribe them, or drop them on a timeline later.

Captioning. Transcribe and caption when the file already contains speech and you want that speech burned in. This is not a text overlay you typed. add_veed_captions transcribes and times; the video must actually have audible speech. Basic presets bill at the standard caption rate; dynamic presets bill at 2x. preview_caption_style trims the first sample_seconds and runs the matching caption path on that slice so you can compare looks without captioning the whole file. Fixed headlines (add_video_captions) and timestamped lines you write yourself (add_timestamped_captions) are different tools: they do not listen. Burned-in captions are pixels. Changing the words later is a new caption job.

How they sit next to the editor, MCP, and REST

The agent is the usual caller. You describe the transform; it picks the utility. The same tools are available through the MCP connector, so a chat in Claude or Cursor can extract a frame or attach a VO without opening a timeline.

Underneath, these jobs hang off /api/v1/features (extract-frames, merge-videos, attach-audio, audio-isolation, add-captions, colorize-photo, editor-render, and related). There is no public API reference site on versely.studio, and there is no customer webhook that POSTs you the result. Extract, merge, and attach return a file URL on the same response. Isolation and VEED captioning insert a generation row and return a request_id — poll GET /api/v1/status/:requestId the same way you would for a generate call. Do not invent a notify URL.

Credits come from the same balance as the app. API calls spend that balance the same way in-app work does. estimate_cost and check_credits exist so a pipeline can price a batch before it dispatches. Captioning and attach each charge as themselves; they are not covered by an editor preview.

A pipeline that uses them as utilities looks like this:

1. Generate or upload sources (HTTPS URLs in the library).
2. isolate_audio on the field VO if the mix is dirty. Poll the returned request_id until you have a vocal-track URL.
3. attach_audio_to_video in replace or mix, depending on whether the picture's original sound should survive.
4. add_veed_captions on that result, after a preview_caption_style sample if the look is still open. Poll that request_id before you treat the captioned file as ready.
5. extract_video_frames on the captioned file for the thumbnail.

No EDL. Each step is a file you might reuse. If step 5's thumbnail is wrong, you do not re-attach audio; you extract a different time.

A pipeline that should have used the editor instead:

1. cut_video on clip A.
2. cut_video on clip B.
3. merge_movie_scenes on those two.
4. attach_audio_to_video.
5. add_veed_captions.

That is one video, described the hard way. Put the clips, trims, music, and captions on one edit_video call, preview at 480p (free, short per-user cooldown), export once.

A rule for which surface to call

• One transform, one file out, and you will use that file again: a features utility.
• Several layers of one video, still in flux: edit_video, not a chain of utilities.
• A still, a stem, or a captioned copy of a locked cut: utility. Do not open a timeline to screenshot, solo, or subtitle.

Prompt examples that keep the agent on the utility:

Extract three frames between 2s and 4s from this clip. I need a thumbnail, not a new video.

Isolate the vocals on this recording. Do not generate new music and do not edit a timeline.

This cut is locked. Mix this bed under the original voice, music quieter, lossless on the picture. Then caption the result in the glass preset. Preview the caption style on the first 4 seconds before you burn the whole file.

Prompt examples that should have gone to the editor:

Cut these, add the music, add captions, make it 9:16.

That last one is an EDL. Sending it through five utilities works, and it is the slow, charged, intermediate-heavy version of one timeline render.

FAQ

Are these only available inside the visual editor?

No. They are standalone jobs. The agent, MCP, and the /api/v1/features routes all call them without opening a timeline. The video editing hub lists the same jobs from the operator side.

Do utilities get the free 480p preview (with its cooldown)?

No. The free 480p pass with a short per-user cooldown is edit_video with preview: true. Attach, isolate, and captioning bill when they run. preview_caption_style is a short caption sample on your own footage, which is a different, cheaper decision aid, not the editor preview.

Can I hook a utility to a webhook so it POSTs me the file?

No. Versely does not offer customer-supplied result webhooks. Take the URL the call returns, or poll status on generation endpoints.

Is isolating vocals the same as splitting a generated song?

No. isolate_audio is for a mixed audio URL. separate_music_vocals is for a Suno track you generated, and it needs that track's ids. Using one in place of the other is the usual misfire.

Call the utility when the utility is the product. Open the editor when the product is a layered cut. The features surface is there so those two instincts stay separate.