Variations
View as MarkdownA 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. maincannot 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
restoreFromVersionIdset to the other's head (undoing a change). - An edit without
expectedHeadVersionIdis 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'shead_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. |