# Variations

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`

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

The response is `201 Created` with the variation:

```json
{ "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](/docs/blitframe/editing#in-a-render) 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](/docs/blitframe/api#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`

```json
{
  "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](/docs/blitframe/projects#edits-and-the-head)).

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

| Request | `variation` |
|---|---|
| [Edit](/docs/blitframe/projects#editing-a-project): `POST /v1/projects/{projectId}/versions` | In the body. The new version becomes that variation's head. |
| [History](/docs/blitframe/projects#versions): `GET /v1/projects/{projectId}/versions` | As a query parameter: `?variation=spanish`. |
| [ZIP import](/docs/blitframe/uploads#use-it): `POST /v1/projects/{projectId}/package` | In the body. |
| [Render](/docs/blitframe/renders#create-a-render): `POST /v1/renders` with `projectId` | In the body: renders that variation's head. |
| [Batch render](/docs/blitframe/renders#batch-renders): `POST /v1/projects/{projectId}/renders/batch` | In the body: every render uses that variation's head. |
| [Share link](/docs/blitframe/sharing#create-a-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](#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](https://app.codeartworks.com/blitframe/), 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](/docs/blitframe/editing#in-a-render) or a [batch](/docs/blitframe/editing#many-videos-from-a-data-sheet). 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](/docs/blitframe/projects#duplicating-a-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](/docs/blitframe/projects#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](#create-a-variation), or both `fromVersionId` and `fromVariation` are sent. |
| Create | `403 project_too_large` | `fromVersionId` is larger than your plan's [project size](/docs/blitframe/limits#plan-limits) 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`. |
