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 keeps the value it has in the project, which is its default_value ("Acme" above). 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 passed into the 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.

Value types

Each value must suit its field. The field’s default_value shows the shape it takes:

Field	Value
Text	A string. A number or true/false is taken as its text.
Number	A number, or a string holding one ("42").
On/off	true or false, or the strings "true" and "false".
Colour	A hex string: "#ff6600", or "#ff6600ff" with alpha (#rgb works too).
Choice	The value of one of the options set in the editor.
Point	An object such as { "x": 960, "y": 540 }, a pair such as [960, 540], or one number for both.
Media	An https:// (or http://) URL on a public host for the render to download. null or "" keeps the field’s own media.
Font	A font family: a Google font or one of the project’s own fonts. A field that offers only some fonts lists them in fonts (get a template) and takes only those.

Values sent as text, as spreadsheets and form posts send them, are read by the field’s type. null counts as not sent, and so does an empty string for every field but text, so a blank spreadsheet cell keeps the field’s default. A value that still doesn’t fit (including a media URL on a private or local address) is rejected with a 400 naming the field key, and nothing is rendered:

{ "error": "Field \"price\" takes a number, got \"forty\"." }

A font is checked when the render starts, so a family that can’t be found fails the render rather than the request. A media URL that can’t be downloaded fails the render the same way, naming the field: a render never quietly shows the template’s own image in its place.

Targets

A template renders one or more targets: the same fields applied to a different composition, such as a 9:16 story and a 16:9 landscape cut. Get a template lists them in targets, in order. The first is the primary.

{
  "id": "tpl_8f2c1d4e6a7b9c0d1e2f3a4b5c6d7e8f",
  "name": "Welcome video",
  "targets": [
    { "key": "story", "name": "Story 9:16", "width": 1080, "height": 1920, "duration": 6 },
    { "key": "landscape", "name": "Landscape 16:9", "width": 1920, "height": 1080, "duration": 6 }
  ]
}

Pass a target’s key as target to render it:

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

Without target, the primary target renders, so a request written before a template had more than one target renders exactly as it did. One request makes one render of one target: to render several targets, send a request for each.

A key the template doesn’t define is a 400 that lists the keys it does:

{ "error": "Template 'tpl_8f2c1d4e6a7b9c0d1e2f3a4b5c6d7e8f' has no target 'square'. Its targets: 'story', 'landscape'." }

target or values without a template_id is also a 400.

default_value is a field’s value in the primary target. Another target can hold a different value of its own, and a field left out of a request for that target uses it.

Each field lists in reaches the keys of the targets it can change. A field that only a story’s caption uses lists ["story"]; a value sent for it when rendering landscape is accepted and changes nothing.

A target’s name is the name of the composition or sequence it renders, so it follows a rename in the editor. Its key doesn’t change: address targets by key.

A render reads back like the request that made it: template_id, target (the key of the target that rendered, the primary’s when the request named none) and values. All three are null for a render made without a template.

{
  "id": "rend_jh716ctpaqbye9aw64tgkqwtks7gvx7g",
  "name": "Welcome - John Smith (landscape)",
  "status": "complete",
  "template_id": "tpl_8f2c1d4e6a7b9c0d1e2f3a4b5c6d7e8f",
  "target": "landscape",
  "values": { "customer_name": "John Smith" }
}

target was an object of key and label until November 2026; it is now the key alone.

A template’s target_composition_id is the primary target’s composition. It stays for existing integrations, but targets supersedes it.

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. Add template_id to list only the renders made from one template.