Preview limits: clip caps, cooldowns, ceilings

The editor's 480p preview is free and carries a 5-second per-user cooldown, and it is not an unbounded render farm. edit_video with preview: true gives you a working draft at 480p, charged at zero credits, gated by three limits that all fire in production: a 10-clip cap, a 180-second duration ceiling, and that cooldown. Miss any one of them and an automated iterate loop looks broken when it is doing exactly what the pipeline was built to do.

The final export is a different call. Set preview false and you get the full-resolution file, billed once as editor_export. On the agent tool, omitting the flag is the same as false. On POST /features/editor-render, preview is a required boolean: leave it out and you get HTTP 400, not a silent export. Every generation still spends credits. The preview pass is the only unpaid render, and the cooldown is part of the deal.

If you are wiring a bot, a script, or an agent loop that "just keeps previewing until it looks right," those three gates are the spec.

The three gates, in the order they usually bite

Cooldown (5 seconds, per user). Consecutive preview requests from the same user are spaced. Fire two previews back to back and the second returns HTTP 429 with retry_after_ms instead of a video_url. Wait that long, then retry. This exists so a tight loop cannot hammer the pipeline. A human editing in chat almost never notices it. A script that previews, mutates the EDL, and previews again in the same second always notices it.

Duration ceiling (180 seconds of content). The preview path will not render more than three minutes of content, meaning the sum of effective clip durations after speed changes. A 15-second clip at 0.25× slow-mo counts as 60 seconds toward the ceiling. A four-minute assembly that is otherwise valid is a preview reject, not a slow preview. Export is a separate path with a higher ceiling (15 minutes of content). Do not treat a preview reject as "the edit is impossible."

Clip-count cap (10). Preview accepts at most 10 clips. The clip array itself allows up to 20 on a real export, so a 12-clip timeline can be a legal final and an illegal preview. If preview is refused for clip count, the timeline is not corrupt. Drop the least-load-bearing clips from the preview EDL, split the assembly into two previewable ranges, or skip preview and export (that last option spends credits, so it is a last resort).

None of these gates apply in the same way to standalone tools. cut_video and attach_audio_to_video have no free 480p preview pass. If your loop is iterating on pacing, music, and captions together, it belongs on edit_video, not on a chain of one-shot utilities.

What a preview is for, and what it is not

A 480p preview pass (still gated by the cooldown, the 10-clip cap, and the 180-second ceiling) is enough to judge:

• Clip order and whether a cut is early or late
• Whether a transition reads as a cut or a smear
• Whether music sits under speech or on top of it
• Whether captions collide with faces or platform UI
• Whether the 9:16 crop guillotines the subject

It is not enough to judge grain, fine text, or whether a logo is sharp. For those, export once you already like the cut. Re-exporting because the preview looked soft is how people spend a second editor_export on a timeline that did not change.

Billing is a count of exports, not of previews. Eight previews and one export is one editor_export. One preview and three exports is three. The preview-and-export scenario is the worked version of that arithmetic.

credits_charged on a successful preview should be zero. If it is not, you did not send preview: true. On the agent tool, the default is false, so forgetting the flag is a billed export. On REST, forgetting the flag is a 400.

An iterate loop that respects all three

Treat the EDL as state. Preview is a function of that state. Export is a one-shot after the state is accepted.

edl = build_timeline(clips, trims, texts, music, captions, ratio)

if duration(edl) > 180s or clip_count(edl) > 10:
    preview_edl = subset_for_preview(edl)   # first 180s, or first 10 clips
else:
    preview_edl = edl

loop:
    wait until last_preview_at + 5s
    result = edit_video(preview_edl, preview=true)
    if result.retry_after_ms:
        wait result.retry_after_ms
        continue
    inspect result.video_url          # 480p
    if notes_require_change:
        edl = apply_notes(edl)
        preview_edl = subset_for_preview(edl)
        continue
    break

edit_video(edl, preview=false)        # one export charge

Five details that make this loop hold:

1. Wait on retry_after_ms, not on a guessed 5 seconds, when the call tells you to wait. The cooldown is 5 seconds; clock skew and a slow previous render still make the returned value the one to honor.
2. Subset before the first preview, not after the third reject. If you know the full cut is 4 minutes, preview the opening 180 seconds (or the hook-plus-payoff range) on purpose. Do not discover the ceiling by failing.
3. Keep the full EDL and the preview EDL distinct. Notes apply to the full timeline. The subset is only what you send with preview: true. Export the full EDL.
4. Do not parallelize previews per user. The gate is per user, not per timeline. Two jobs previewing "at once" for the same account will trip each other.
5. Stop the loop on inspect, not on hope. 480p will not get sharper on the fifth pass. If the remaining questions are resolution questions, export.

In chat, the same loop is just slower and less formal:

Build this six-clip edit, 9:16, music under the VO, captions on. Preview at 480p. Wait if you are still inside the cooldown.

Then:

Take 400ms off the start of clip 2, preview again.

Then:

Looks right. Export.

Ask the agent to assemble from clips, music, and captions with the preview flag stated in the first message. If you omit it, you get a final.

When the caps force a different shape

The cut is longer than 180 seconds. Preview the region you are actually deciding. A mid-video caption collision does not require a preview of minute 1. Build a preview EDL that starts 20 seconds before the problem and ends 20 seconds after, still under the ceiling. Keep the full timeline for export. Alternatively, split a 6-minute piece into two exported parts if the published form is two videos anyway.

The clip list is longer than 10. You do not have to delete footage from the real EDL. For the preview pass, keep the first 10 clips, or collapse consecutive B-roll into one representative clip. You are checking pacing and mix, not proving that clip 12 exists. The full editor still holds the complete list for the charged render, up to 20 clips.

You need a still, not a motion preview. Extracting a frame is a different tool, not a preview. If the question is "does this thumbnail work," pull stills from the video rather than burning cooldown on a 480p encode.

You are iterating on caption look alone. preview_caption_style renders the first few seconds of your video in a candidate preset. That is a caption decision aid, billed as a short sample, not the editor's 480p timeline preview. Use it when the cut is locked and the question is glass versus whisper. Use edit_video previews when the cut is not locked.

You are about to export a batch. Check the credit balance before the finals. Previews will not save you from a 402 on export. There is no unpaid export path.

Clips still have to be HTTPS workspace or generation URLs. A local path fails before any cap is evaluated.

FAQ

Is the 480p preview really free?

Yes. preview: true charges zero credits. It is limited by a 5-second per-user cooldown, a 10-clip cap, and 180 seconds of content. The only unpaid render on Versely is this pass. Every generation, and every final editor export, spends credits.

What should my code do with retry_after_ms?

Sleep for that many milliseconds, then resubmit the same preview. Do not flip preview to false to "get around" the cooldown. That turn is a billed export, and you will still want a preview after it.

If preview rejects my timeline, did I lose the edit?

No. The EDL is your state, not the preview file. Shorten or thin the preview EDL, or export the original. A duration or clip-cap reject is not a corrupt project.

Can I run two preview loops at once on one account?

Not reliably. The cooldown is per user. Two loops will take turns getting retry_after_ms. Serialize previews for a given user, or accept that they queue.

Wire the three gates into the loop and preview stays a cheap, boring, correct way to cut. Ignore them and the same feature reads as rate-limiting, a mysterious clip error, and a three-minute wall, usually all in the same afternoon.