# Renders and previews

> A render is a queued job that produces the final file and uses your export allowance. A preview is an instant frame or composition that costs nothing.

## Renders

`POST /v1/renders` queues an export of the project's saved document and answers `202` straight away with a job. The job moves through these statuses:

| Status | Meaning |
| --- | --- |
| `PENDING` | Queued, waiting for a render slot. |
| `PROCESSING` | Rendering. `progress` goes from 0 to 100. |
| `COMPLETED` | Done. `url` is the file. |
| `FAILED` | It did not render. `error` says why. |
| `CANCELLED` | Stopped before it finished. |

The plan decides the rest, and the response's `applied` object tells you what it decided: the maximum output height (a project taller than the cap renders at half height), whether a watermark is added, and render priority. A plan also limits how many renders run at once and, on some plans, how many exports a month; over either limit the request is refused with `402 quota_exceeded` and nothing is queued.

## Knowing when it is done

Subscribe a [webhook](https://developer.vidmoat.com/developer/docs/webhooks) to `render.completed` and `render.failed`. Keep a bounded poll of `GET /v1/renders/{id}` (every five seconds, for a few minutes) as a fallback for a missed delivery.

> **Warning: Never queue the same render twice after a timeout.** A lost response does not mean the render was not queued, and every queued render uses an export. List `GET /v1/renders?projectId=…` to find the job you already started.

## Previews

`GET /v1/projects/{id}/preview` answers three different questions, none of which use your export allowance:

- **Is the layout right?** The default JSON answer: duration, canvas, layout `lint` and `suggestedPreviewTimes`. Starts no browser.
- **What does this exact frame look like?** `?format=image&at=2.5` returns a JPEG drawn by the same pipeline as the export. Ten frames a minute per key.
- **Can I scrub it in a page?** `?format=html` returns an approximate HTML composition. For an exact, interactive player in your own UI, embed `/embed/player`.

The [video preview guide](https://developer.vidmoat.com/developer/docs/preview) walks through all of them.

---

Source: https://developer.vidmoat.com/developer/docs/concepts/renders-and-previews
Previous: [Projects and commands](https://developer.vidmoat.com/developer/docs/concepts/projects-and-commands.md)
Next: [Credits and plans](https://developer.vidmoat.com/developer/docs/concepts/credits-and-plans.md)
All documentation: https://developer.vidmoat.com/llms-full.txt