Projects and versions

View as Markdown

A 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 a restoreFromVersionId, replaces what the head has, including changes made since.
  • Replacements name layers by their position in data.json, which a newer data.json can 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 offsetSeconds into 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 audio overrides 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.
  • restoreFromVersionId can be any version of the project; any other id is 404 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.
  • expectedHeadVersionId is optional, as in any edit. With it, the restore is refused with 409 head_moved if someone edited the project after you chose the version.
  • Add files, delete or replacements to 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.

  • fromVersionId can 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 renderable and problems are 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 name different 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, COM0 to COM9, LPT0 to LPT9), with or without an extension, such as con.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.png and images/logo.png, or only in how an accented letter is encoded, as é can be one character or e plus an accent (400).
  • A file copied with fromVersionId keeps its file type. The root data.json copies only to and from another version's root data.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 fromVersionId that doesn't exist or belongs to another workspace is 404 not_found. fromVersionId together with zipUploadId is 400 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.
  • copiedFromProjectId finds copies only while that project exists. copiedFromVersionId finds 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.