Versely
    Guides

    Why the editor rejects local file paths

    Clip sources must be reachable over HTTPS, so file:// paths fail immediately. Upload or attach first, then render from the hosted URL.

    Versely Team••7 min read

    edit_video will not read /Users/you/Desktop/take-03.mp4. It will not read file:///Users/you/Desktop/take-03.mp4, a C:\Users\... path, a content:// URI from a phone, or a blob: URL from a browser tab. The call fails before a frame is decoded. The pipeline only fetches clip sources over HTTPS, from media it can actually reach: a file already in your workspace, or a prior generation.

    That is not a fussy parser. The render runs on Versely's side. Your laptop's filesystem is not on that network. A local path is an address the renderer cannot follow, so it is rejected the same way any other non-HTTPS scheme is rejected.

    The fix is a staging step, not a retry. Host the file, get an HTTPS URL, then call render.

    What the editor will actually fetch

    The clips argument is required. Every item has to be an HTTPS media URL. file:// and other local schemes are rejected. http://localhost, *.local hosts, and private IPv4 ranges (10.x, 192.168.x, 172.16–31.x) are rejected too: they look like URLs and still point at a machine the renderer cannot fetch. Music, voiceover, and overlay URLs go through the same check.

    attach_audio_to_video is the same rule on a single file: video and audio must already be reachable HTTPS URLs. If you generate speech or music inside Versely, those results arrive hosted. If you recorded the voiceover in another app, that WAV has to land in the library before you can mix it.

    A successful edit_video call, preview or final, returns a video_url (HTTPS), credits_charged, and preview_notes. The inputs and the output live in the same kind of place. The timeline never becomes a pile of files on disk.

    What this is not: a ban on using your own footage. Your footage is welcome. It has to be uploaded first so the renderer has a URL. The video editor and the agent assembly flow both assume that.

    The staging step, in order

    Do this before the first edit_video call, not after the first failure.

    1. Get the file into Versely. Attach it in chat, or upload it in the app so it lands in your library. Do not paste a desktop path into the prompt and hope the agent will magically open it.
    2. Confirm you have an HTTPS URL. Ask the agent to find something you made or uploaded. Under the hood that is browse_user_library for uploads, slideshows, and UGC overlays, fetch_user_generations for AI outputs, and search_my_media when you remember the subject but not the file. The thing you want back is a https:// URL, not a filename.
    3. Only then describe the edit. Pass those URLs as clips. Add music, voiceover, captions, aspect ratio as needed. Ask for a 480p preview first (preview: true). That preview is free and carries a short per-user cooldown; the final export is the one charge.
    4. Keep the URLs. The EDL stores references, not baked pixels. If you save the timeline as a draft, those HTTPS clip URLs are what the draft points at. A local path would have been useless here even if the first render had somehow worked, because next week's machine would not have that path either.

    A prompt that skips staging and fails:

    Edit /Users/alex/Desktop/hooks/hook-a.mp4 and /Users/alex/Desktop/hooks/hook-b.mp4 together with this music file on my disk.

    A prompt that stages, then renders:

    I just uploaded two product clips and a voiceover. Find those in my library, then assemble them in that order with a short crossfade, 9:16, and give me a 480p preview.

    The second prompt makes the agent look up hosted URLs before it touches edit_video. That lookup is the staging step.

    What to do with footage that is not in the library yet

    Phone recordings and camera cards. Copy them off the device into the app (or attach them in the chat that will do the edit). Do not try to point the editor at a Photos library path or an SD-card mount.

    Files already on object storage you control. The documented input is a workspace or generation HTTPS URL. Upload or attach so Versely hosts a copy, then use that URL. A signed URL that expires mid-render is a later failure that looks like a path error. YouTube watch-page links are not clip sources; dubbing says this outright for external links, and you should not assume the editor is more lenient.

    Outputs of other Versely tools. These are already staged. A clip from text-to-video, a track from the music generator, a voiceover from generated speech: each comes back with a hosted URL. Drop that URL on the timeline. Do not download to disk and re-upload unless you have a reason.

    Workflow reference assets (characters, products, locations). That is a different upload path. request_asset_upload opens an Asset Builder card so a saved video workflow can reuse a character or product by key across scenes. It is not how you stage B-roll for edit_video. Mix those up and the asset exists in the workflow library while the editor still has nothing to fetch.

    Failure modes that look like path errors but are not

    Once you are passing HTTPS URLs, a failed render is usually something else.

    • The URL is HTTPS but not yours. A signed URL that expired, a page URL rather than a media URL, a thumbnail instead of the video. Fetch the library item again and use the media URL it returns.
    • Audio and video both need hosting. People fix the clip paths and then pass ~/Music/bed.wav as music. Stage the bed the same way, or generate it inside Versely so the URL already exists.
    • Preview versus export. A preview rejection for clip count or duration is not a path error. The 480p preview (preview: true, short per-user cooldown) also caps previews at 10 clips and 180 seconds of content. Path errors happen immediately and do not depend on how long the timeline is.
    • Insufficient credits on the final. A real export returns a 402-style error if the balance cannot cover editor_export. That is unrelated to schemes. Check credits before a batch of finals; previews do not spend that charge.

    If you automate this, the check is mechanical: before you call render, assert every clip, music, voiceover, and overlay URL starts with https:// and came from the library or a generation. Reject the job in your own code if a path sneaks in. Waiting for Versely to reject file:// works, but it wastes a round trip and produces a failure that looks like an editor bug when it is an input bug.

    FAQ

    Can I unzip a folder of takes and point the editor at the folder?

    No. There is no folder input. Each clip is one HTTPS URL. Upload the takes (or attach them), collect the URLs, then pass that list as clips in order.

    Why does a file I can play locally still fail?

    Because the player on your machine can see your disk and the renderer cannot. Local playback is not evidence that the pipeline can fetch the file. The evidence you need is a workspace or generation HTTPS URL.

    Do generated clips need this staging step?

    No. A generation already returns a hosted URL. Use it. Downloading the MP4 and re-uploading it is how people accidentally introduce file:// paths into a pipeline that was already correct.

    Is the preview pass more lenient about paths?

    No. Preview and final share the same clip-source rule. preview: true changes resolution, billing (free, with a short per-user cooldown), and the preview caps. It does not accept local files.

    Stage first, render second. The editor is not refusing your footage. It is refusing an address it cannot fetch. Put the file in the library, take the HTTPS URL, and then ask for the cut.