Editing layers
View as MarkdownChange a project's text, fonts, images and video by layer, without rewriting data.json. Change the project with an edit, change one video with a render, or make one video per row of 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
{
"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 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) 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). |
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. A render takes uploadId only. Images also take fit. |
- 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.listif 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,
wandh(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
{
"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. Check renderable and problems in the response as usual.
- Like any edit, it applies to the head as it is then, of
mainor of the variation named invariation. SendexpectedHeadVersionIdto be sure the layers are still where you read them (edits and the head). - Replacements work on the
data.jsonthe edit starts from: the head's, or that ofrestoreFromVersionId. So an edit can't also send a newdata.jsoninfiles(400). - Without a
message, the version's message lists what changed, such asEdit Headline text, Product image. - Replacements that change nothing (the same text, font and file the version already has) create no version, like any edit that changes nothing. The response is
200 OKwith the current head.
In a render
POST /v1/renders
{
"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.
- The render pins a version: the
versionIdyou name, or withprojectIdthe head ofmainor of the variation invariation. The response'ssourceVersionIdis that version, at once. - Blitframe then makes the render's own version: the pinned version with the replacements applied and images fitted. Meanwhile the render is
queuedand itsversionIdisnull. Its text is fitted when it renders. - Usually within seconds,
versionIdis 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). You can also start a variation at it with fromVersionId, or duplicate it into a separate project.
A render can change only layers, so its replacements differ from an edit's:
- No
files,delete, newdata.jsonorsoundtrack. Add files that many renders share to the project with an edit first, and reference them withpath. - A new image or video comes from an upload:
filetakes apaththat is not in the version and anuploadId, nevercontentBase64. Each upload goes in one render, and is used up when that render's version is made. - A
fontis a library font slug, or a font file already in the pinned version. - The render's
audio.pathmust 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 lists the answers for uploads.
The pinned version's text fitting rules fit each render's text, measured against its baseline. 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).
Many videos from a data sheet
To make a video per row of a spreadsheet, product feed or translation table, send one batch render of the project. Each row's changes are that render's replacements:
POST /v1/projects/{projectId}/renders/batch
{
"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 ofmainor of the variation named invariation. The response'sversionIdsays which, so edits made while the batch runs never mix into it. - Each row has its own
format,quality,frames,audio,nameandreplacements. 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 it and give itsuploadId. - 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. Download the finished videos as one ZIP with a download archive.
Send an Idempotency-Key header with the batch, so a retry after a lost answer cannot queue it twice (idempotency).
To keep a version and edit it over time, such as one per language or brand, use a variation or a copy of the 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).
Layer details
- Layer ids stay the same in versions changed with replacements, because replacements never add, remove or reorder layers.
textFitcounts rules from the version'stext_fitting.json, and a layer's ownt.textFitwith alayerregion (the only inline rule the engine reads). On a version withproblemsit is alwaysfalse.- 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 totext,name,font,assetId,fonts[].name,familyandstyle. Readdata.jsonfor the whole value.
Replacement details
- A replaced image or video layer's asset must declare
wandh, each from 1 to 4096. Otherwise the replacement is refused with400 invalid_request. - A font file added in the same edit can't be used in
fontyet. 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 withversion_not_renderable. ItsversionIdis 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 itsversionIdstaysnull. For example, an upload was used elsewhere first. Or the replacements' files would take the version over 8 GB (version_not_renderabletoo): use smaller files. - Either way the render is refunded like any failed render (pricing).
- Cancelling a render while its version is being made cancels it at once.