Projects and versions
View as MarkdownA project holds one composition: its data.json and the files it uses. This page shows how to create a project, edit it, undo a change, copy it and export a version.
Create a project
The example creates a project, then adds data.json from the current folder as its first version. It reads BLITFRAME and BLITFRAME_API_KEY from the environment, set as in the quickstart.
PROJECT_ID=$(curl -s -X POST $BLITFRAME/projects \
-H "Authorization: Bearer $BLITFRAME_API_KEY" -H "Content-Type: application/json" \
-d '{"name":"Summer ad"}' | jq -r .id)
jq -Rs '{files: [{path: "data.json", content: .}]}' data.json |
curl -s -X POST $BLITFRAME/projects/$PROJECT_ID/versions \
-H "Authorization: Bearer $BLITFRAME_API_KEY" -H "Content-Type: application/json" \
-d @- | jq '{renderable, problems}'
import os, requests
api = os.environ["BLITFRAME"]
headers = {"Authorization": f"Bearer {os.environ['BLITFRAME_API_KEY']}"}
project = requests.post(f"{api}/projects", headers=headers, json={"name": "Summer ad"}).json()
project_id = project["id"]
with open("data.json", encoding="utf-8") as file:
files = [{"path": "data.json", "content": file.read()}]
version = requests.post(f"{api}/projects/{project_id}/versions", headers=headers, json={"files": files}).json()
print(version["renderable"], version["problems"])
import { readFile } from "node:fs/promises";
const api = process.env.BLITFRAME;
const headers = { Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}`, "Content-Type": "application/json" };
const project = await (
await fetch(`${api}/projects`, { method: "POST", headers, body: JSON.stringify({ name: "Summer ad" }) })
).json();
const projectId = project.id;
const files = [{ path: "data.json", content: await readFile("data.json", "utf8") }];
const response = await fetch(`${api}/projects/${projectId}/versions`, {
method: "POST",
headers,
body: JSON.stringify({ files }),
});
const version = await response.json();
console.log(version.renderable, version.problems);
<?php
function call(string $method, string $path, array $body): array {
$ch = curl_init(getenv("BLITFRAME") . $path);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("BLITFRAME_API_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode($body),
]);
return json_decode(curl_exec($ch), true);
}
$project = call("POST", "/projects", ["name" => "Summer ad"]);
$projectId = $project["id"];
$files = [["path" => "data.json", "content" => file_get_contents("data.json")]];
$version = call("POST", "/projects/$projectId/versions", ["files" => $files]);
var_dump($version["renderable"], $version["problems"]);
require "net/http"
require "json"
def call(method, path, body)
uri = URI(ENV["BLITFRAME"] + path)
headers = { "Authorization" => "Bearer #{ENV["BLITFRAME_API_KEY"]}", "Content-Type" => "application/json" }
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
http.send_request(method, uri.request_uri, body.to_json, headers)
end
JSON.parse(response.body)
end
project = call("POST", "/projects", { name: "Summer ad" })
project_id = project["id"]
files = [{ path: "data.json", content: File.read("data.json", encoding: "utf-8") }]
version = call("POST", "/projects/#{project_id}/versions", { files: files })
p version["renderable"], version["problems"]
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
)
func call(method, path string, body any) map[string]any {
payload, err := json.Marshal(body)
if err != nil {
panic(err)
}
req, err := http.NewRequest(method, os.Getenv("BLITFRAME")+path, bytes.NewReader(payload))
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("BLITFRAME_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var out map[string]any
if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
panic(err)
}
return out
}
func main() {
project := call("POST", "/projects", map[string]any{"name": "Summer ad"})
projectID := project["id"].(string)
data, err := os.ReadFile("data.json")
if err != nil {
panic(err)
}
files := []map[string]any{{"path": "data.json", "content": string(data)}}
version := call("POST", "/projects/"+projectID+"/versions", map[string]any{"files": files})
fmt.Println(version["renderable"], version["problems"])
}
using System.Net.Http.Json;
using System.Text.Json.Nodes;
var api = Environment.GetEnvironmentVariable("BLITFRAME");
var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("BLITFRAME_API_KEY"));
async Task<JsonNode> call(HttpMethod method, string path, object body)
{
var request = new HttpRequestMessage(method, api + path) { Content = JsonContent.Create(body) };
var response = await http.SendAsync(request);
return (await response.Content.ReadFromJsonAsync<JsonNode>())!;
}
var project = await call(HttpMethod.Post, "/projects", new { name = "Summer ad" });
var projectId = (string?)project["id"];
var files = new[] { new { path = "data.json", content = await File.ReadAllTextAsync("data.json") } };
var version = await call(HttpMethod.Post, $"/projects/{projectId}/versions", new { files });
var problems = version["problems"]!.AsArray().Select(p => (string?)p);
Console.WriteLine($"{version["renderable"]} [{string.Join("; ", problems)}]");
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
public class Example {
static JsonNode call(String method, String path, String body) throws Exception {
HttpRequest request = HttpRequest.newBuilder(URI.create(System.getenv("BLITFRAME") + path))
.header("Authorization", "Bearer " + System.getenv("BLITFRAME_API_KEY"))
.header("Content-Type", "application/json")
.method(method, HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
return new ObjectMapper().readTree(response.body());
}
public static void main(String[] args) throws Exception {
JsonNode project = call("POST", "/projects", """
{"name": "Summer ad"}
""");
String projectId = project.get("id").asText();
String content = new ObjectMapper().writeValueAsString(Files.readString(Path.of("data.json")));
JsonNode version = call("POST", "/projects/" + projectId + "/versions", """
{"files": [{"path": "data.json", "content": %s}]}
""".formatted(content));
System.out.println(version.get("renderable") + " " + version.get("problems"));
}
}
The second request prints whether the new version can render, and its problems. If they list missing images or fonts, add those files in another edit.
Each edit saves a new version, a snapshot of every file that never changes, and moves the project's head to it. Concepts explains the model.
All requests go to https://blitframe.codeartworks.com with an Authorization: Bearer <api key> header, and bodies are JSON.
POST /v1/projects can also start a project from a ZIP or from another version:
| Body | Creates |
|---|---|
{ "name": "Summer ad" } |
An empty project. The name is 1 to 200 characters. |
{ "name": "…", "zipUploadId": "…" } |
A project whose version 1 is a ZIP upload. |
{ "name": "…", "fromVersionId": "…" } |
A copy of a version (duplicating a project). |
Send at most one of zipUploadId and fromVersionId. An Idempotency-Key header makes a retry safe (retrying safely).
Editing a project
POST /v1/projects/{projectId}/versions
{
"expectedHeadVersionId": "b7e2…",
"message": "Change headline to Spanish",
"files": [
{ "path": "data.json", "content": "{ \"v\": \"5.12.2\", … }" },
{ "path": "images/logo.png", "contentBase64": "iVBORw0KGgo…" },
{ "path": "video/background.mp4", "uploadId": "1c9d…" },
{ "path": "fonts/Inter-Bold.ttf", "fromVersionId": "4f0a…" }
],
"delete": ["images/old-logo.png"]
}
An edit makes a new version from the head plus your changes, and moves the head to it. Files you don't mention carry over from the head unchanged. The response is 201 Created with the new version.
| Field | Description |
|---|---|
files |
Files to add or replace. Each has a path and one source. |
delete |
Paths to remove from the head's files. |
expectedHeadVersionId |
Optional. The head your change was made on. If the head has moved since, the edit is refused with 409 head_moved (edits and the head). |
message |
Optional description, cut off at 500 characters. Defaults to Update, or with replacements to a list of what changed, such as Edit Headline text. |
name |
Optional version name, up to 200 characters, such as Approved cut. It is set when the version is created and never changes. Download file names use it. |
variation |
Optional. The variation to edit, such as spanish. Defaults to main. |
fontLicenseAccepted |
Must be true when files adds a font file, except one copied with fromVersionId. It confirms you are licensed to render with it (fonts). |
restoreFromVersionId |
Optional. Start from this version's files instead of the head's (undoing a change). |
replacements |
Optional. Change text, fonts, images or video by layer without sending data.json (replacements). |
soundtrack |
Optional. The audio renders play by default (soundtrack). |
textFittingBaselineVersionId |
Optional, with text_fitting.json in the version. The earlier version, from the variation's history, that text fitting measures originalBounds against. |
An edit that changes nothing makes no version. It answers 200 OK with the current head (when an edit makes no version).
Send an Idempotency-Key header to make a retry safe. The same edit with the same key answers with the version the first one made (retrying safely). An edit that names uploads is safe to send again even without a key (edits that name uploads).
Files
Each item in files has a path and exactly one source:
| Source | Sends |
|---|---|
content |
UTF-8 text, such as data.json. |
contentBase64 |
A binary file, inside the request. |
uploadId |
A ready upload whose fileName has the same extension as path. |
fromVersionId |
A file copied from any version in your workspace, without uploading it. fromPath names it there and defaults to path (copy files). |
The whole request body can be up to 64 MB. Base64 makes files about a third larger, so contentBase64 fits files up to about 45 MB. Upload anything bigger.
Edits and the head
An edit applies to the head as it is when the edit runs: the head of main, or of the variation the edit names. If another edit lands first:
| Your edit | What happens |
|---|---|
Without expectedHeadVersionId, or with null |
There is no check. Your edit is made again on the new head. After three tries in all, it is refused with 409 head_moved: send it again. |
With expectedHeadVersionId |
The head must still be that version. If it isn't, the edit is refused with 409 head_moved and nothing changes. Get the project (or the variation), apply your change on its new head, and send it again. |
Without expectedHeadVersionId, your change goes on the head even if someone edited the project after you read it. That suits a change that doesn't depend on what you read, such as adding a file. Send expectedHeadVersionId when it does:
- A whole
data.json, or arestoreFromVersionId, replaces what the head has, including changes made since. - Replacements name layers by their position in
data.json, which a newerdata.jsoncan change.
Edits to one variation never move another's head, so they never cause each other's head_moved.
Soundtrack
"soundtrack": { "path": "audio/music.mp3", "offsetSeconds": 0 } sets the audio a render of this version plays. The path must be an audio file in the version.
- The audio starts
offsetSecondsinto the video (0 to 3,600). The video is silent until then, and the file plays from its beginning. - Audio stops where the video ends, so an offset at or past the video's length gives a silent video.
- Later versions keep the soundtrack while its file stays. To remove it, delete the audio file.
- A render's own
audiooverrides it for that render (renders).
Paths and file types
Paths are relative, use forward slashes (images/logo.png) and are 1 to 512 characters. The composition is always data.json at the root. File rules lists the characters a path can't use.
| Kind | Extensions |
|---|---|
| Composition and data | .json |
| Images | .png, .jpg, .jpeg, .jfif, .tga, .webp, .avif, .heic, .heif, .tif, .tiff, .bmp, .gif, .psd |
| Video | .mp4, .mov, .m4v, .webm, .mkv, .avi, .mpg, .mpeg, .wmv, .flv, .ts, .mts, .m2ts |
| Audio | .mp3, .wav, .m4a, .aac, .flac, .ogg, .oga, .opus (any codec that decodes; renders convert it to AAC) |
| Fonts | .ttf, .otf, .woff, .woff2 |
| 3D models | .glb and .gltf, self-contained |
Each file's contents are checked against its extension. A version holds up to 5,000 files. GET /v1/files/capabilities returns this list with each type's size and dimension limits (file capabilities). How media files render covers animated images, PSD files and video with alpha.
Undoing a change
Versions are never changed or deleted, so you undo by editing again. Set restoreFromVersionId to the version to go back to:
{ "expectedHeadVersionId": "b7e2…", "restoreFromVersionId": "4f0a…", "message": "Back to the English headline" }
- The new version has exactly the files and soundtrack of
4f0a…, and becomes the head. The versions in between stay in the history. restoreFromVersionIdcan be any version of the project; any other id is404 not_found. That includes one from another variation's history, and the version a render with replacements made, which keeps that render's changes in the project.expectedHeadVersionIdis optional, as in any edit. With it, the restore is refused with409 head_movedif someone edited the project after you chose the version.- Add
files,deleteorreplacementsto change something at the same time.
Variations
A variation is a second head in a project, with its own history, such as the video in Spanish next to the original. Every project has one called main, which requests use when they name no variation. Variations shows how to create, edit, render and delete one.
Duplicating a project
To copy a version into a project of its own, create a project with fromVersionId. Use it for a copy you will keep editing apart, such as one for a partner:
POST /v1/projects
{ "name": "Summer ad (Spanish)", "fromVersionId": "b7e2…" }
The response is 201 Created with the new project. The head of its main has that version's files, soundtrack, name and message.
fromVersionIdcan be any version in your workspace, of any project, including the version a render made.- A version larger than your plan's project size is copied only when a head of its project is at least as large. Otherwise, such as a render's own version that its replacements made larger, the copy is
403 project_too_large. - Only that version is copied. Its history, other variations, renders and share links are not.
- When the version's text fitting measures against another version (baseline), that version is copied first. The new project then starts with two versions and fits text exactly as the original does.
- Nothing is uploaded again. A copy is quick whatever its size, and needs no
fontLicenseAccepted. - The copy is checked again in the new project, so its
renderableandproblemsare current. - Edits to the copy never change the original, and the reverse.
To find copies, list projects with copiedFromVersionId for the copies of one version. Use copiedFromProjectId for the copies of any version of a project, such as every language of a project. Copy details has the refusals and what happens when the original is deleted.
To make many one-off videos, or to keep an alternative in the same project, you don't need a copy (variation, copy or replacements).
Versions
| Method | Path | Does |
|---|---|---|
GET |
/v1/projects/{projectId}/versions?variation=&limit=50&before={versionId} |
The history of main, or of the variation named, newest first: the head, then each version's parent. limit is 1 to 1,000 (default 50). Pass next as before to page. |
GET |
/v1/versions/{versionId} |
One version with its files, composition details, problems and warnings. |
GET |
/v1/versions/{versionId}/files/{path} |
Redirects (302) to a short-lived download link for one file. |
POST |
/v1/versions/{versionId}/export |
Queue a ZIP of the whole version (exporting a version). |
GET |
/v1/versions/{versionId}/export/{exportId} |
The export's status and, once ready, its download link. |
The history lists the versions the head was made from. A version that a render with replacements made is in no history, unless a variation starts at it. Get it by the render's versionId.
A version looks like this:
{
"id": "b7e2…",
"projectId": "9a0f…",
"parentVersionId": "4f0a…",
"number": 5,
"message": "Change headline to Spanish",
"createdAt": "2026-11-05T20:00:00+00:00",
"composition": { "width": 1920, "height": 1080, "frameRate": 30, "durationSeconds": 6, "frameCount": 180 },
"renderable": true,
"problems": [],
"warnings": [],
"soundtrack": null,
"textFittingBaselineVersionId": null,
"files": [{ "path": "data.json", "sizeBytes": 48211, "contentType": "application/json", "sha256": "…" }],
"name": "Approved cut"
}
| Field | Meaning |
|---|---|
parentVersionId |
The version this one was made from, or null for a project's first version. A render's version has the version the render pinned. |
number |
Counts up across the project. Versions made by renders and by edits to other variations take numbers too, so a history can skip one. |
composition |
Read from data.json, or null when it cannot be read. |
renderable |
true when problems is empty. |
files |
The version's files. It is null on each item of the history list: get the version for its files. |
soundtrack |
The default render audio, or null (soundtrack). |
textFittingBaselineVersionId |
The version text fitting measures original text against, or null. |
Problems and warnings
problems lists everything that stops the version from rendering. Fix them in another edit. For example:
- a missing
data.json, or invalid JSON, - an asset or font that is not in the version,
- a shape or text layer with nothing to draw,
- composition values outside Blitframe's limits, such as a frame rate above 120.
At most 50 problems are listed. A last entry says when there are more.
warnings list things that render, but differently than you might expect:
- An odd width or height. MP4 and HLS video need even dimensions.
- A text fitting rule that could not be applied, or text that cannot fit at its
minSize. - Characters a font has no glyphs for. They render as the font's missing-glyph symbol, usually an empty box. The warning names the layer, the font and the characters.
- A text layer Blitframe could not check for missing glyphs or overflowing text. Its font cannot be measured, or would take the version's fonts past 128 MB.
To change text, fonts, images or video without rewriting data.json, see Editing layers.
Project files
GET /v1/projects/{projectId}/files?kind=image&q=logo&limit=100&after=… lists every distinct file across the project's versions, sorted by path:
{
"items": [
{ "path": "images/logo.png", "kind": "image", "sizeBytes": 48211, "contentType": "image/png", "sha256": "9f86…", "versionId": "b7e2…", "versionNumber": 5 }
],
"next": "NTppbWFnZXMv…"
}
A path whose content changed between versions appears once per content. versionId is the latest version holding that exact file. Use it to download the file, or to copy it into an edit with fromVersionId.
| Parameter | Description |
|---|---|
kind |
Optional: composition (the root data.json), json, image, video, audio, font or model. |
q |
Optional: part of the path, any case, up to 200 characters. |
limit |
1 to 1,000, default 100. |
after |
The next value of the previous page. |
Exporting a version
POST /v1/versions/{versionId}/export (no body) queues one ZIP of every file in the version. The ZIP has the layout you would upload, so you can import it into another project, or into this one. The response is 202 Accepted with the export.
Get it with GET /v1/versions/{versionId}/export/{exportId}. Send Prefer: wait=N to hold the answer until it is ready or failed:
{
"id": "…",
"versionId": "b7e2…",
"status": "ready",
"fileName": "Summer-ad-v5.zip",
"url": "https://…",
"sizeBytes": 18211933,
"error": null,
"createdAt": "2026-11-05T20:00:00+00:00",
"finishedAt": "2026-11-05T20:00:04+00:00",
"expiresAt": "2026-11-06T20:00:00+00:00"
}
status |
Meaning |
|---|---|
queued |
Waiting to be built. |
building |
Being built. |
ready |
url downloads the ZIP. The link lasts up to an hour. Get the export again for a fresh one. |
failed |
error (code and message) says why. interrupted means the build stopped on Blitframe's side. Request a new export. |
With a webhook, version_export.ready or version_export.failed tells you when it is done.
A renderable version's text fitting is applied to the exported data.json, and text_fitting.json is left out. Importing the export keeps the fitted text but not the rules.
Limits has the export's size, lifetime and queue limits. Export details has the rest.
List, rename and delete projects
| Method | Path | Does |
|---|---|---|
GET |
/v1/projects?q=&copiedFromVersionId=&copiedFromProjectId=&limit=100&before= |
List projects, newest first. |
POST |
/v1/projects |
Create a project (create a project). |
GET |
/v1/projects/{projectId} |
Get one project. |
PATCH |
/v1/projects/{projectId} |
Rename it: { "name": "…" }. |
DELETE |
/v1/projects/{projectId} |
Delete the project with its variations, versions, renders and share links. Cancel its queued and running renders first, or you get 409 renders_active. |
GET |
/v1/projects/{projectId}/files |
List every file across its versions (project files). |
POST |
/v1/projects/{projectId}/package |
Import a ZIP upload as the next version of main, or of the variation it names: { "zipUploadId": "…" } (uploads). Takes an Idempotency-Key header. |
GET |
/v1/projects/{projectId}/package/{importId} |
Status of an import that answered 202 (large ZIPs). |
The list takes these parameters:
| Parameter | Description |
|---|---|
q |
Part of the project name, up to 200 characters. |
copiedFromVersionId, copiedFromProjectId |
Only the copies of that version, or of any version of that project. |
limit |
1 to 1,000, default 100. |
before |
The next value of the previous page, for older projects. Lists end when next is null. |
A project looks like this:
{
"id": "9a0f…",
"name": "Summer ad",
"createdAt": "2026-11-05T19:00:00+00:00",
"headVersionId": "b7e2…",
"renderable": true,
"copiedFromVersionId": null,
"thumbnailUrl": "https://…"
}
| Field | Meaning |
|---|---|
headVersionId |
The head of the project's main variation. Edits and renders of the project use it when they name no other variation. null while the project is empty. |
renderable |
Whether that head can render, or null while the project is empty. The head's problems say why not. |
copiedFromVersionId |
For a copy, the version it was made from. It is kept even after that version's project is deleted. null for any other project. |
thumbnailUrl |
The poster of the project's latest succeeded MP4 or HLS render, or null before there is one. The link lasts an hour. |
Details
When an edit makes no version
An edit makes no version when the files, soundtrack and text fitting baseline end up exactly as the head has them. That happens with no files, with the same content again, or when you restore the head itself. A new version is still made when:
- the edit names an upload (making a version is what uses the upload up),
- the head has
problems(the files are checked again, so anything that has become available since is picked up), - the edit gives a
namedifferent from the head's, or - the project is empty (its first edit always makes a version, even with no files).
Edits that name uploads
An edit that names uploads can be sent again exactly as it was after it used them. It answers 200 OK with the version it made and the header Idempotent-Replayed: true, even without an Idempotency-Key. So retrying after a lost answer is safe. A different edit that names an upload already used is 400 invalid_request.
File rules
- Paths cannot start with
/. They cannot contain\,.or..segments, control characters or any of" : * ? < > |, so an exported ZIP unzips on any system. For the same reason no folder or file name may end in a dot or a space, or be a name Windows reserves (CON,PRN,AUX,NUL,COM0toCOM9,LPT0toLPT9), with or without an extension, such ascon.png(400). - A version's files can total at most your plan's project size. An edit that makes a version larger is
403 project_too_large. One that keeps a version already past it the same size or smaller is accepted. - Two paths in a version cannot differ only in letter case, such as
images/Logo.pngandimages/logo.png, or only in how an accented letter is encoded, asécan be one character oreplus an accent (400). - A file copied with
fromVersionIdkeeps its file type. The rootdata.jsoncopies only to and from another version's rootdata.json.
How media files render
| File | How it renders |
|---|---|
| Animated GIF and WebP | Plays once as video, then holds its last frame. |
| PSD | Renders its merged composite. |
| TIFF and AVIF | Must hold a single image. |
| Video with alpha | Keeps its alpha. ProRes 4444, QuickTime Animation or PNG in MOV or MP4, upright and at most 4096 pixels on each side, is used as it is. Other video with alpha is converted to PNG in MOV. Export alpha video premultiplied (matted) against black. |
| Other video that needs converting | Becomes H.264, or PNG in MOV when its width or height is odd. Rotated video is turned upright. Full-range or BT.2020 video is re-encoded with the BT.709 matrix in limited range, without converting BT.2020 colors (format reference). |
Copy details
- A
fromVersionIdthat doesn't exist or belongs to another workspace is404 not_found.fromVersionIdtogether withzipUploadIdis400 invalid_request. - A version larger than your plan's project size can still be copied.
- If the original project is deleted later, the copy keeps its
copiedFromVersionId, but the id no longer leads to a version. copiedFromProjectIdfinds copies only while that project exists.copiedFromVersionIdfinds them after it is deleted too.
Export details
- A version over 8 GB in total is refused with
400. Download its files one by one. - A workspace can have 10 exports waiting or building. Another gets
409 export_limit. Each workspace builds one export at a time. - Asking again for a version whose export is queued, building, or ready with more than an hour before it expires returns that same export.
- Exports are kept for 24 hours.