Preview

Building with an AI agent? POST /v1/preview is the fast inner loop: validate for free, glance at a frame or a whole-timeline contact sheet, then only call POST /v1/renders once it looks right. For visual review, use this native preview. Open the browser only for editor interaction: the editor draws its own preview, so it is not evidence of how the render looks.

How preview works

Preview reuses the exact same render pipeline and renderer as POST /v1/renders — same engine, same JSON schema — just restricted to a slice of the timeline and downscaled. What you see in a preview is exactly what the full render produces at that timestamp.

Submit POST /v1/preview with a render_request composition.
Choose what you want:
- dry_run: true — validate only, no render, returns instantly.
- at: <seconds> — a single frame.
- window: { from, to } — a short clip, with audio.
- contact_sheet: { ... } — a grid of frames sampled across the timeline.
Get a response immediately — 200 for a dry run, no job (a contact-sheet dry run also includes the sampling plan, still with no job). Any non-dry-run preview — frame, window, or contact sheet — returns 202 with a job queued.
Poll like any render — job.id (prefix render_) works with GET /v1/renders/{id}. Preview jobs are free: excluded from your usage totals and from GET /v1/renders.

Free validation (`dry_run`)

Set dry_run: true to run Framelane’s linter without spending a render: duplicate element IDs, dangling or self-referencing transitions, an empty timeline, an element or caption that starts after the composition ends, an entrance motion timed later than the element it belongs to, an audio element hidden with visible: false (which drops the track rather than muting it), a track matte whose source layer is never on screen while the element it drives is, the canvas-space findings (off-frame boxes, colliding text, unreadable sizes and contrast, a drop shadow whose offset rounds to nothing), the structure of the v5 blocks (operations, frames, components and instances, below), and, if you pass target_duration_sec, a timeline that misses your target length. A dry run also runs the full translator and reports every feature the real submit would reject — an unsupported field, a motion preset used on the wrong element type, a zero-offset shadow, a word_animation combined with motion[], a transition pointing at a non-video, a dangling group member or matte source. Each arrives as severity: "error" with the same message the 422 would carry, so ok: true means the composition will submit. Run it before every POST /v1/renders.

{
  "render_request": { "...": "..." },
  "dry_run": true
}

{
  "kind": "validation",
  "ok": false,
  "violations": [
    {
      "code": "DANGLING_TRANSITION",
      "message": "transitions[0].from_id references an unknown element",
      "severity": "error",
      "path": "transitions[0]"
    }
  ],
  "job": null
}

ok is false only when a violation is severity: "error" — a missed target_duration_sec, for example, is a "warning" and never blocks you. Each violation says where it happened twice: path, an index path such as elements[0].children[2].text_color, and pointer, the same place as an RFC 6901 JSON pointer (/elements/0/children/2/text_color). target_id is the id of the element, frame, instance or group the finding is about (inside an instance, its expanded path, such as card1/title), or null when it names none.

Structural findings (v5 blocks)

Frames, instances, operations and components are checked on the whole document before the renderer sees them, and each code mirrors the renderer’s own name. All are errors but the two marked warning. The canvas-space findings (off-frame, overlap, size, contrast, shadow) measure root elements only: inside a frame or an instance they say nothing.

Code	What it means
`UNKNOWN_TARGET`	An operation’s `target` or an `element.*` anchor’s names nothing in the request, or a split asks for units its target has none of (`child` on a leaf, `letter`, `word` or `line` on a non-text).
`GROUP_OP_NEEDS_CHILD_SPLIT`	An operation or preset entry targets a frame, an instance or a group, which has no element of its own: split it by `child` or target a child.
`SPLIT_UNIT_TEXT_NOT_STATIC`	A `letter`, `word` or `line` split on a counter, whose string changes every frame, so it is skipped.
`PROPERTY_NOT_ON_KIND`	The `property` does not apply to the target’s kind, or to its own data (a solid fill has no stops, a rect no ring, a text without `glow` no glow).
`BAD_PROPERTY_INDEX`	An index in the `property` is past the end of the target’s list (`effects`, `fill.stops`, `stroke_dash`, ring segments, geometry shadows).
`PROPERTY_NOT_DRAWN`	The target’s kind holds the `property` but the renderer does not draw it, or a letter, word or line split drives something other than position, rotation and tint.
`PROPERTY_TYPE_MISMATCH`	A `from` or `to` of the wrong type: a string on a number path, a number on `text.value`.
`PROPERTY_OUT_OF_RANGE`	A replace’s `from` or `to` is outside the path’s range (opacity and colours are 0 to 1).
`COMPOSITE_NOT_ALLOWED_ON_PATH`	The path does not take that `composite` (multiply is for scale, opacity and colours).
`TAKEOVER_NOT_ALLOWED`	`takeover` on an operation that is not a replace without `from` on a path that is not stepped.
`OVERLAPPING_REPLACES`	Two replaces of one property on one target overlap in time, so the later cuts the earlier off; one that sets `takeover` is meant to.
`OP_OUTSIDE_TARGET_WINDOW`	Warning: the operation runs outside the time its target is on screen.
`PROPERTY_ALSO_DRIVEN_BY_PRESET`	Warning: the target also runs a `motion` preset that drives position, scale, rotation, opacity or tint, which applies on top of the operation.
`DANGLING_MATTE_SOURCE`	A nested element’s `matte.source` names no element of the request.
`DUPLICATE_ELEMENT_ID`	Also reported for an id used twice anywhere in the tree, frame children and slot content included.
`INSTANCE_COMPONENT_UNKNOWN`	An instance names a component `components` does not define.
`INSTANCE_VARIANT_UNKNOWN`	An instance, or a `variant` property’s value, names a variant its component does not have.
`INSTANCE_PROPERTY_UNKNOWN`	An instance sets a property its component does not declare.
`INSTANCE_PROPERTY_TYPE_MISMATCH`	A property value or `default` is not of the property’s type (values are never coerced).
`INSTANCE_PROPERTY_VALUE_NOT_ALLOWED`	A number outside its `min` and `max`, or a component not in `allowed`.
`INSTANCE_SLOT_UNKNOWN`	An instance fills a slot its variant does not have.
`INSTANCE_PROPERTY_INVALID`	A component declares a property twice, or allows a component the request does not define.
`INSTANCE_COMPONENT_INVALID`	A component id or a variant name used twice, or a body node without an id, with a duplicate id, with the component’s own id, or a slot marked twice.
`INSTANCE_ID_RESERVED_SEPARATOR`	An id contains `/`, which separates instance paths.
`INSTANCE_COMPONENT_BINDING_UNKNOWN`	A `bind` path names no node of some variant, a field that cannot be bound, or a nested property its component does not declare.
`INSTANCE_COMPONENT_BINDING_TYPE_MISMATCH`	A property binds a field of another type.
`INSTANCE_COMPONENT_BINDING_CONFLICT`	One field is bound twice.
`INSTANCE_COMPONENT_BINDING_INTO_SLOT`	A binding names a node inside a slot frame, whose content an instance may replace.
`INSTANCE_COMPONENT_REFERENCE_UNKNOWN`	A body’s operation target, anchor target or matte source names no node of the variant outside slot content.
`INSTANCE_COMPONENT_ANCHOR_NOT_LOCAL`	A component’s group is anchored at `composition` or names a target for `instance.start`.
`INSTANCE_COMPONENT_SWAP_INCOMPATIBLE`	A component a `component` property may swap in does not declare, with the same type, a property the swapped instance sets or is passed.
`INSTANCE_COMPONENT_CYCLE`	A component contains itself through its instances or `allowed` lists.
`INSTANCE_PATH_UNKNOWN`	An instance path such as `card1/subtitle` names no node of the expanded tree.
`INSTANCE_ANCHOR_INSTANCE_UNKNOWN`	An `instance.start` anchor names no instance.
`INSTANCE_MATTE_SOURCE_HIDDEN`	A matte source is omitted by `visible: false`.
`INSTANCE_DEPTH`	Instances nest more than 8 deep.
`INSTANCE_NODE_CAP`	The expanded tree would hold more than 10,000 leaves or 10,000 frames.
`INSTANCE_OPERATION_CAP`	The expanded operations, every instance’s included, would number more than 10,000.
`INSTANCE_GROUP_CAP`	The expanded operation groups would number more than 1,000.

A layout key on a frame or an instance (layout, gap, padding, align and the like) is a 422 of type layout_key_unknown that names the key and the frame: the renderer lays nothing out, so place each node at its own x and y in design px.

Dry-run `ok` vs. submit-path `ok`

The same two fields appear in two different roles, and only one of them is a gate:

Surface	Status	What `ok` means
`POST /v1/preview` with `dry_run: true`	`200`	A gate. Nothing was rendered and nothing was spent. `ok: true` means the composition will submit; `false` means fix it first — unless a `LINT_UNAVAILABLE` warning is present, which means our linter itself failed and the composition was not checked. To fail closed, gate on `ok` and `LINT_UNAVAILABLE` not being among the codes.
`POST /v1/renders`, `POST /v1/projects/{id}/renders`	`202`	Advisory. The render is already queued and billable. `ok: false` tells you the output will probably be wrong, not that the request was refused.
`POST /v1/projects`	`201`	Advisory. The project is stored at version 1 either way — a project is meant to hold an invalid head while you repair it with ops.

The dry run is strictly the more informative of the two, because it runs the full translator: a feature the submit path rejects shows up there as an error, whereas on the submit path that same problem is a 422 and there is no body to attach it to. What the advisory lint adds is the handful of findings a strict translation does not cover — a self-referencing transition, a fully off-canvas element, a sub-pixel drop shadow — reported on the render you just paid for so you are not left comparing the artifact against your intent. If the linter itself fails, the submit still goes through and you get a single LINT_UNAVAILABLE warning with ok: true. That is a server-side fault, not a statement about your composition.

Frame and window previews

Pass at for a single frame, or window: { from, to } for a short clip (audio trimmed and muxed for free). Both render at a small draft width by default (480 px; raise width up to 3840 for a sharper look) and dispatch a real, cheap render job.

{
  "render_request": { "...": "..." },
  "at": 4.0,
  "width": 480
}

{
  "kind": "frame",
  "ok": true,
  "violations": [],
  "job": { "id": "render_01J...", "is_preview": true, "status": "queued" }
}

Poll job.id via GET /v1/renders/{id} exactly like a full render.

at and window are mutually exclusive. A window.to past the end of the composition is clamped down to the composition’s duration rather than rejected — you may get a shorter clip than requested, never an error. A window.from at or past the composition’s duration is rejected, with 422 invalid_request. An at past the end of the composition is clamped to the last frame, not rejected.

Contact sheets: see the whole edit in one image

Set contact_sheet to get back a single grid PNG sampling frames across the timeline — enough to check an entire edit in one glance (or one vision call), without downloading and scrubbing a video.

{
  "render_request": { "...": "..." },
  "contact_sheet": { "detail": "balanced", "max_cells": 4 }
}

Framelane samples at meaningful moments — the first and last frame, where each element starts, each transition, and each caption’s first word — then fills any remaining budget uniformly (bare { "detail": "balanced" } on a 10-second composition budgets ~10 cells; max_cells caps that, shown here at 4 to keep the example short). The sheet field describes the plan immediately (even on a dry_run, before any render happens):

{
  "kind": "contact_sheet",
  "ok": true,
  "sheet": {
    "columns": 2,
    "rows": 2,
    "width": 480,
    "window": { "from": 0, "to": 10 },
    "cells": [
      { "index": 0, "at": 0.0, "reason": "first_frame" },
      { "index": 1, "at": 4.0, "reason": "element_start" },
      { "index": 2, "at": 6.5, "reason": "caption" },
      { "index": 3, "at": 9.97, "reason": "last_frame" }
    ]
  },
  "job": { "id": "render_01J...", "is_preview": true, "status": "queued" }
}

Option	Type	Description
`detail`	`"overview"` \| `"balanced"` \| `"detailed"`	Cell budget: ~9 / ~16 / ~36 cells, capped down for short clips. Default `"balanced"`. The count is rounded to one that fills the grid, so a 5s clip yields 6 cells in a 3×2 — never 5 with a dead slot.
`columns`	integer 1–12	Grid columns. Defaults to a near-square layout. Pinning it rounds the cell count to a whole number of rows; a `columns` wider than the tier budget can fill is honoured as asked and leaves a short last row.
`max_cells`	integer 1–64	Hard cap on cell count, below the `detail` tier’s budget. A cap that cannot fill a grid rounds down to one that can (`13` → 12 cells in a 4×3), so the sheet stays hole-free.

Combine with window to sample only part of the timeline instead of the whole thing. Once the render completes, job.output.url is a single PNG — columns × cellWidth pixels wide, rows × cellHeight tall — with each cell’s frame and burned-in label ("0:04 element_start") matching sheet.cells[i] in order. GET /v1/renders/{id}/poster redirects to a signed URL for the sheet PNG — the embeddable counterpart to /download.

Request reference

Field	Type	Description
`render_request`	object	The composition to preview.
`at`	number ≥ 0	Single-frame preview, in timeline seconds. Exclusive with `window` and `contact_sheet`.
`window`	`{ from, to }`	Clip preview range, in timeline seconds. `to` must be greater than `from`.
`contact_sheet`	object	See table above. May be combined with `window` to bound its span.
`width`	integer 16–3840	Preview width in px; height derives from the composition’s aspect ratio. Default `480`.
`dry_run`	boolean	Validate only, no render. Default `false`.
`target_duration_sec`	number > 0	Optional target timeline length; a mismatch surfaces as a `TARGET_DURATION_MISSED` warning.
`target_tolerance_sec`	number ≥ 0	Tolerance around `target_duration_sec`. Default `0.5`.

Endpoints

Method	Path	Description
`POST`	`/v1/preview`	Validate or preview a composition

Good to know

Preview jobs cost nothing and are excluded from GET /v1/renders and GET /v1/workspace/usage — build as many as you need while iterating.
A preview is pixel-identical to the equivalent full render at the same timestamp, modulo resolution — the renderer takes no different code path for a preview, so what you approve (once scaled up) is what you’ll get.
Preview requests never accept Idempotency-Key — every call creates a new job.
If an element references media you haven’t finished uploading yet, a real preview (dry_run: false) returns 422 asset_not_ready; a dry_run: true validation tolerates it and lints the rest of the composition anyway.

Get Started

Renders

Render Examples

Recipes

Projects

Tasks

Webhooks

Guides

SDKs

How preview works

Free validation (`dry_run`)

Structural findings (v5 blocks)

Dry-run `ok` vs. submit-path `ok`

Frame and window previews

Contact sheets: see the whole edit in one image

Request reference

Endpoints

Good to know

​How preview works

​Free validation (dry_run)

​Structural findings (v5 blocks)

​Dry-run ok vs. submit-path ok

​Frame and window previews

​Contact sheets: see the whole edit in one image

​Request reference

​Endpoints

​Good to know

How preview works

Free validation (`dry_run`)

Structural findings (v5 blocks)

Dry-run `ok` vs. submit-path `ok`

Frame and window previews

Contact sheets: see the whole edit in one image

Request reference

Endpoints

Good to know