Variations

View as Markdown

A variation keeps a second head in the same project, such as the video in Spanish or in a partner's colors next to the original. This page shows how to create one, edit and render it, and delete it.

Create a variation

POST /v1/projects/{projectId}/variations

{ "name": "spanish", "fromVariation": "main" }

The response is 201 Created with the variation:

{ "name": "spanish", "headVersionId": "c41d…", "createdAt": "2026-11-12T10:00:00+00:00" }

Creating a variation makes no version. Its head is the version it starts at, until you edit it.

Field Description
name 1 to 100 characters: ASCII letters (a to z), digits, -, _ and ., starting with a letter or digit. Names are kept in lower case, so Spanish and spanish are the same variation.
fromVariation Optional. Start at this variation's head.
fromVersionId Optional. Start at this version of the project: one from any variation's history, or the version a render with replacements made.

Send at most one of fromVariation and fromVersionId. With neither, the variation starts at main's head. The project needs a version first. Send an Idempotency-Key header to make a retry safe (retrying safely).

A project has at most 100 variations, main included. Every project has main, made with the project. Requests that name no variation use it, and the project's headVersionId and renderable are its.

Edit and render a variation

Name the variation in variation. This edit changes the headline of spanish, on the head you read:

POST /v1/projects/{projectId}/versions

{
  "variation": "spanish",
  "expectedHeadVersionId": "c41d…",
  "replacements": [{ "layer": "/layers/0", "text": "Rebajas de verano" }]
}

The new version becomes the head of spanish. The head of main does not move. expectedHeadVersionId is compared with the head of spanish (edits and the head).

These requests take variation. Without it, they use main.

Request variation
Edit: POST /v1/projects/{projectId}/versions In the body. The new version becomes that variation's head.
History: GET /v1/projects/{projectId}/versions As a query parameter: ?variation=spanish.
ZIP import: POST /v1/projects/{projectId}/package In the body.
Render: POST /v1/renders with projectId In the body: renders that variation's head.
Batch render: POST /v1/projects/{projectId}/renders/batch In the body: every render uses that variation's head.
Share link: POST /v1/projects/{projectId}/share-links In the body: the link follows that variation's head.

A request that pins a version with versionId renders or shares that version, so it takes no variation. Refusals lists what is refused.

List variations

Method Path Does
GET /v1/projects/{projectId}/variations The project's variations, main first, then by name: { "items": [ … ], "next": null }.
GET /v1/projects/{projectId}/variations/{name} One variation.

headVersionId is the variation's head. Only main's is ever null, while the project is empty. In the console, a project with more than one variation shows a link to each, with its history.

Delete a variation

DELETE /v1/projects/{projectId}/variations/{name} answers 204 No Content.

  • Its versions stay in the project. Renders, exports and share links pinned to one of them keep working, and you can still use any of them by id.
  • Share links that follow the variation's head are deleted with it. Their pages answer 404.
  • main cannot be deleted.

Variations cannot be renamed. To change a name, create a variation with fromVariation set to the old one, then delete the old one.

Variation, copy or replacements?

You want Use
Videos made once from data, such as one per row of a data sheet Replacements in a render or a batch. No head moves.
A lasting alternative you edit and render again, next to the original A variation. Its versions sit in the same project as the original's, so each can restore the other's with restoreFromVersionId.
A separate project, with its own name, renders and share links Duplicate the project.

Details

Versions and history

  • A variation's history runs from its head through each parent. So it includes the versions the variation started from, and they appear in the history of every variation that shares them.
  • Versions belong to the project, not to a variation. Get, render, export or restore any of them by id.
  • To bring a variation back in line with another, edit it with restoreFromVersionId set to the other's head (undoing a change).
  • An edit without expectedHeadVersionId is made again on its variation's newer head, if another edit lands first. Edits to one variation never move another's head, so they never cause each other's head_moved.

Refusals

Request Answer When
Create 400 invalid_request The project is empty: edit it or import a ZIP first.
Create 400 invalid_request The name breaks the rules, or both fromVersionId and fromVariation are sent.
Create 403 project_too_large fromVersionId is larger than your plan's project size and than every head of the project, such as a render's own version that its replacements made larger.
Create 404 not_found The project, or the fromVariation, does not exist, or fromVersionId is not a version of this project.
Create 409 variation_exists The project already has a variation with that name.
Create 409 variation_limit The project already has 100 variations. Delete one first.
Delete 400 invalid_request The variation is main.
Get or delete 404 not_found The project has no variation with that name.
Any request that takes variation 404 not_found The project has no variation with that name.
Render, batch or share link 400 invalid_request variation is sent with versionId.