Renders

A render is a video file produced from a project. When you create a render, Edit Square takes the project as it exists at that moment, applies the values you supply, and renders the result to a video file.

Lifecycle

A render moves through the following statuses:

Status	Meaning
initializing	The render was accepted and its configuration is being prepared.
ready	The configuration is prepared and the render is waiting for a worker.
queued	The render has been handed to a worker.
processing	The render is in progress. The first progress report moves it here.
finalizing	Rendering finished. The file is being stored and the credits charged.
complete	The render is finished. output carries the file URLs.
failed	The render stopped with an error. There is no output to collect.

complete and failed are final; the other five are steps along the way.

Applying values

template_id names a template defined in the project, and values is an object keyed by that template’s field keys. For example, this template from Get a template exposes a single field, customer_name:

{
  "id": "tpl_8f2c1d4e6a7b9c0d1e2f3a4b5c6d7e8f",
  "name": "Welcome video",
  "fields": [
    {
      "key": "customer_name",
      "label": "Customer name",
      "default_value": "Acme"
    }
  ]
}

Each entry in values sets the field with the matching key. To render this template for a customer named John Smith, the following would be used:

{
  "name": "Welcome - John Smith",
  "project_id": "proj_jd71dcg41pjy7rax1v2h4pvcmd7gtar9",
  "template_id": "tpl_8f2c1d4e6a7b9c0d1e2f3a4b5c6d7e8f",
  "values": { "customer_name": "John Smith" }
}

A field you leave out falls back to its default_value ("Acme" above), and keys the template does not define are ignored. A template_id the project does not define is an error, not a silent fall-through to the plain project.

The values are applied to a copy of the project configuration for this render only. The project itself is untouched, so two renders from the same project with different values never affect each other.

The full request body is documented in Create a render.

Outputs

A complete render carries an output object of signed URLs, keyed by variant: the master file, plus any smaller encodes the project produces.

The URLs are signed and time-limited. Download the file, or re-request the render to get fresh URLs; they are not stable links to hand to a browser weeks later.

The full response is documented in Get a render.

Tracking a render

There are two ways to follow a render to completion:

• Polling: Request GET /v1/renders/{id} until the status is either complete or failed. This is simple and works well at small volume. A typical render takes a couple of minutes, so poll on that scale.
• Webhooks: Edit Square calls your endpoint when the render changes state. We recommend webhooks for anything unattended or at volume. See Webhooks.

Listing renders

GET /v1/renders lists a project’s renders, newest first. project_id is required: renders are listed per project, not per team.