# Editing layers

Change a project's text, fonts, images and video by layer, without rewriting `data.json`. Change the project with an [edit](#in-an-edit), change one video with a [render](#in-a-render), or make one video per row of a [data sheet](#many-videos-from-a-data-sheet).

All requests go to `https://blitframe.codeartworks.com` with an `Authorization: Bearer <api key>` header.

## Editable layers

List a version's layers to find the ids that replacements use:

`GET /v1/versions/{versionId}/layers`

```json
{
  "width": 1920,
  "height": 1080,
  "textLayers": [
    { "layer": "/layers/0", "name": "Headline", "text": "Summer sale", "font": "Montserrat-Bold", "fontSize": 72, "textFit": true }
  ],
  "imageLayers": [
    { "layer": "/layers/3", "name": "Product", "assetId": "image_1", "path": "images/product.png", "width": 800, "height": 800 }
  ],
  "videoLayers": [
    { "layer": "/assets/2/layers/0", "name": "Background", "assetId": "video_1", "path": "video/beach.mp4", "width": 1920, "height": 1080 }
  ],
  "fonts": [
    { "name": "Montserrat-Bold", "family": "Montserrat", "style": "Bold", "source": "library" }
  ],
  "audioFiles": ["audio/music.mp3"],
  "soundtrack": null
}
```

| Field | Meaning |
|---|---|
| `layer` | The layer id that replacements use: its position in `data.json` as a JSON pointer. Layers inside a precomposition start with `/assets/{n}/layers/`. |
| `textFit` | `true` when a [text fitting](/docs/blitframe/text-fitting) rule fits the layer's text to its space. |
| `path`, `width`, `height` | The file the layer shows, and the pixel size its asset declares. |
| `fonts[].source` | `project` (a font file in the version), `library` (the [shared font library](/docs/blitframe/fonts)) or `missing`. |
| `audioFiles`, `soundtrack` | Audio files in the version, and the version's default soundtrack if it has one. |
| `text`, `name`, `font`, `assetId`, `fonts[].name`, `family`, `style` | As `data.json` has them. A very long value is cut ([layer details](#layer-details)). |

A layer inside a precomposition that is used several times changes in every place it appears.

## Replacements

`replacements` is a list of layer changes, the same in an edit and in a render. An edit or a render can replace up to 200 layers, each once. In a batch, each render can.

| Layer | Fields |
|---|---|
| Text | `text`: the new text, not empty. `font`: a library font slug from `GET /v1/fonts`, such as `montserrat-bold`. Or the path of a font file already in the version, named `Family-Style`, such as `fonts/Inter-Bold.ttf`. Send either or both. |
| Image or video | `path`: a file already in the version. Or `file`: a new file at a path not in the version yet, such as `images/new-photo.png`. Send exactly one. `file` takes `contentBase64` or `uploadId`, like an [edit's file](/docs/blitframe/projects#editing-a-project). A render takes `uploadId` only. Images also take [`fit`](#fit-a-new-image-to-the-layer). |

- Text keeps its style. Size, color, tracking, alignment and animation stay as they are. Only the text changes, and the font when you send one.
- A new font is added to `fonts.list` if the composition doesn't declare it yet.
- A new image or video can replace either kind of media. The layer then becomes an image or video layer to match the file.
- The layer's asset must declare its size, `w` and `h` ([replacement details](#replacement-details)).

### Fit a new image to the layer

The layer keeps the size its asset declares, so it stays where the design put it. Blitframe draws the new image into a PNG of exactly that size and adds it to the version next to your file, named `{name}-fit-{hash}.png`. Your original file is kept too.

| `fit` | Result |
|---|---|
| `contain` (default) | The new image fits inside the space the original artwork took, centered on it. Transparent margins and faint shadows are ignored when sizing, so a logo replaces a logo at the same visual size. |
| `cover` | The new image fills everything the original drew, cropping what falls outside. Use it for backgrounds. |

Animated GIF and WebP files are not fitted. They play as video and, like a video replacement, fill the layer's declared size, so use one with the same aspect ratio as the original. `fit` is refused for video.

## In an edit

`POST /v1/projects/{projectId}/versions`

```json
{
  "message": "Spanish text",
  "replacements": [
    { "layer": "/layers/0", "text": "Rebajas de verano", "font": "montserrat-bold" },
    { "layer": "/layers/3", "path": "images/product-42.png", "fit": "contain" },
    { "layer": "/assets/2/layers/0", "file": { "path": "video/city.mp4", "uploadId": "1c9d…" } }
  ],
  "soundtrack": { "path": "audio/music.mp3", "offsetSeconds": 0 }
}
```

An edit's `replacements` change the head's `data.json` for you and create a new version. They go next to the edit's usual `files`, `delete` and [`soundtrack`](/docs/blitframe/projects#soundtrack). Check `renderable` and `problems` in the response as usual.

- Like any edit, it applies to the head as it is then, of `main` or of the [variation](/docs/blitframe/variations) named in `variation`. Send `expectedHeadVersionId` to be sure the layers are still where you read them ([edits and the head](/docs/blitframe/projects#edits-and-the-head)).
- Replacements work on the `data.json` the edit starts from: the head's, or that of `restoreFromVersionId`. So an edit can't also send a new `data.json` in `files` (`400`).
- Without a `message`, the version's message lists what changed, such as `Edit Headline text, Product image`.
- Replacements that change nothing (the same text, font and file the version already has) create no version, like any [edit](/docs/blitframe/projects#editing-a-project) that changes nothing. The response is `200 OK` with the current head.

## In a render

`POST /v1/renders`

```json
{
  "projectId": "9a0f…",
  "format": "mp4",
  "name": "Rebajas de verano",
  "replacements": [
    { "layer": "/layers/0", "text": "Rebajas de verano" },
    { "layer": "/layers/3", "file": { "path": "images/product-es.png", "uploadId": "1c9d…" } }
  ]
}
```

A render's `replacements` change those layers for that video only. The project, its head and its history stay as they are.

1. The render pins a version: the `versionId` you name, or with `projectId` the head of `main` or of the [variation](/docs/blitframe/variations) in `variation`. The response's `sourceVersionId` is that version, at once.
2. Blitframe then makes the render's own version: the pinned version with the replacements applied and images fitted. Meanwhile the render is `queued` and its `versionId` is `null`. Its text is fitted when it renders.
3. Usually within seconds, `versionId` is set to the new version, and the render waits for a GPU as usual.

Replacements that change nothing render the pinned version itself, so `versionId` equals `sourceVersionId`. To reproduce the video, render that `versionId` again without replacements. To keep the change in the project, edit the project with `restoreFromVersionId` set to it ([undoing a change](/docs/blitframe/projects#undoing-a-change)). You can also start a [variation](/docs/blitframe/variations#create-a-variation) at it with `fromVersionId`, or [duplicate](/docs/blitframe/projects#duplicating-a-project) it into a separate project.

A render can change only layers, so its replacements differ from an edit's:

- No `files`, `delete`, new `data.json` or `soundtrack`. Add files that many renders share to the project with an edit first, and reference them with `path`.
- A new image or video comes from an [upload](/docs/blitframe/uploads): `file` takes a `path` that is not in the version and an `uploadId`, never `contentBase64`. Each upload goes in one render, and is used up when that render's version is made.
- A `font` is a library font slug, or a font file already in the pinned version.
- The render's `audio.path` must be an audio file in the pinned version.
- Replacements never change the composition's size or length, so the render costs what the pinned version would.

When you queue the render, each replacement is checked against the pinned version. Its layer must exist and be of the right kind, and its `font` and `path` must exist. A replaced media layer's asset must declare `w` and `h`, and each upload must be ready. A refused render is not queued or charged. Bad replacements get `400 invalid_request`. [When an upload is refused](#when-an-upload-is-refused) lists the answers for uploads.

The pinned version's text fitting rules fit each render's text, measured against its [baseline](/docs/blitframe/text-fitting#baseline-version). So longer text still fits the design. The render's version shows the result in its `warnings`, such as text that cannot fit at its `minSize` or characters its font lacks.

If the render's version has `problems`, or cannot be made, the render fails and is refunded like any failed render ([when a render's version fails](#when-a-renders-version-fails)).

## Many videos from a data sheet

To make a video per row of a spreadsheet, product feed or translation table, send one [batch render](/docs/blitframe/renders#batch-renders) of the project. Each row's changes are that render's replacements:

`POST /v1/projects/{projectId}/renders/batch`

```json
{
  "versionId": "b7e2…",
  "renders": [
    {
      "name": "Spain",
      "replacements": [
        { "layer": "/layers/0", "text": "Rebajas de verano" },
        { "layer": "/layers/3", "path": "images/product-42.png" }
      ]
    },
    {
      "name": "France",
      "replacements": [
        { "layer": "/layers/0", "text": "Soldes d'été" },
        { "layer": "/layers/3", "file": { "path": "images/product-fr.png", "uploadId": "1c9d…" } }
      ]
    },
    { "name": "Original", "format": "hls" }
  ]
}
```

- Every render uses the one version the batch pins: `versionId`, or without it the head of `main` or of the [variation](/docs/blitframe/variations) named in `variation`. The response's `versionId` says which, so edits made while the batch runs never mix into it.
- Each row has its own `format`, `quality`, `frames`, `audio`, `name` and `replacements`. A row without replacements renders the pinned version as it is.
- A file that many rows use: add it to the project with one edit first, then reference it with `path`. A file only one row uses: [upload](/docs/blitframe/uploads) it and give its `uploadId`.
- Every row is checked before anything is queued. If one is refused, nothing is queued or charged, and the error message starts with the row, such as `renders[1]: …`. The whole batch is one charge.
- Rows without replacements wait for a GPU at once. Rows with replacements have their versions made one after another, usually a few seconds each, then wait for a GPU too.

Follow the renders with `POST /v1/renders/statuses` or [webhooks](/docs/blitframe/webhooks). Download the finished videos as one ZIP with a [download archive](/docs/blitframe/renders#download-many-videos-as-one-zip).

Send an `Idempotency-Key` header with the batch, so a retry after a lost answer cannot queue it twice ([idempotency](/docs/blitframe/renders#idempotency)).

To keep a version and edit it over time, such as one per language or brand, use a [variation](/docs/blitframe/variations) or a [copy of the project](/docs/blitframe/projects#duplicating-a-project).

## Details

A batch holds up to 1,000 renders. An edit or render takes up to 200 replacements, and each replacement image up to 128 MB. The request body of an edit, render or batch can be up to 64 MB ([limits](/docs/blitframe/limits#renders)).

### Layer details

- Layer ids stay the same in versions changed with replacements, because replacements never add, remove or reorder layers.
- `textFit` counts rules from the version's `text_fitting.json`, and a layer's own `t.textFit` with a `layer` region (the only inline rule the engine reads). On a version with `problems` it is always `false`.
- A text value longer than 16,383 characters, the most the engine draws of a text, is cut to its first 16,383 and ends with `…`. That applies to `text`, `name`, `font`, `assetId`, `fonts[].name`, `family` and `style`. Read `data.json` for the whole value.

### Replacement details

- A replaced image or video layer's asset must declare `w` and `h`, each from 1 to 4096. Otherwise the replacement is refused with `400 invalid_request`.
- A font file added in the same edit can't be used in `font` yet. Add it in an edit first.
- The fitted image's path must fit in 512 characters too. A long file name is shortened to make room. When the folder alone leaves no room, the replacement is refused with `400 invalid_request`, so keep the folder to 489 characters or fewer.

### Where a render shows its replacements

A render's `replacements` show what you sent, in the response to `POST /v1/renders` and when you get the render with `GET /v1/renders/{renderId}`. Render lists, statuses, cancel responses, the batch response and webhooks leave them out.

### When an upload is refused

A render that names an upload that is not usable is refused, and nothing is charged:

| Upload | Answer |
|---|---|
| Does not exist, belongs to another workspace, has expired, was created more than 46 hours ago, or has another extension than its `path` | `400 invalid_request` |
| Not completed yet | `409 upload_incomplete` |
| Still being checked | `409 upload_processing` |
| Failed its check | `409 upload_failed` |

Queueing the render extends its uploads' expiry to a day from then, but never past 47 hours after each was created.

### When a render's version fails

- If the render's version has `problems`, the render fails with `version_not_renderable`. Its `versionId` is that version, so get it to read them.
- If the version cannot be made at all, the render fails with the reason in its `error`, and its `versionId` stays `null`. For example, an upload was used elsewhere first. Or the replacements' files would take the version over 8 GB (`version_not_renderable` too): use smaller files.
- Either way the render is refunded like any failed render ([pricing](/docs/blitframe/renders#pricing)).
- Cancelling a render while its version is being made cancels it at once.
