Quickstart

View as Markdown

Go from an API key to a downloaded MP4 in five steps. You need no files of your own: step 3 sends a small sample composition. Each request is shown in curl, Python, Node.js, PHP, Ruby, Go, C# and Java.

Starting from an After Effects project, or with a coding agent? See Other ways to start.

Before you start

Your language needs:

Language What it needs
curl jq, to build request bodies and read responses
Python requests
Node.js Node.js 18 or later. The steps run as one ES module: save them in a .mjs file, such as hello.mjs, and run node hello.mjs.
PHP PHP 8.1 or later, with the curl extension
Ruby Ruby 3.0 or later
Go Go 1.21 or later
C# .NET 8
Java Java 17 or later, and Jackson to read JSON

Run the steps in order, in one shell or one file. Step 2 sets up the client, and the later steps reuse it. In Go and Java, the later steps go inside main. Concepts explains the terms on the way: project, version, head and render.

1. Get an API key

Create a Code Artworks account with your work email address and confirm it. Sign-up refuses addresses from free mail services. Your first workspace starts on a free trial, so you need no card.

Open Console → API keys and create a key. Keep it secret: anyone with it can use your workspace. Every request sends it in a header:

Authorization: Bearer blitframe_...

Put the key and the API address in environment variables:

export BLITFRAME_API_KEY=blitframe_...
export BLITFRAME=https://blitframe.codeartworks.com/v1

The console's Overview and API keys pages show the BLITFRAME_API_KEY command and a first request ready to paste, with the key filled in right after you create it. They also show how to connect MCP. Anywhere else, replace blitframe_... with your key. The console lets you look at your projects and renders. You create and render them through the API or MCP.

2. Create a project

PROJECT_ID=$(curl -s -X POST $BLITFRAME/projects \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Hello Blitframe"}' | jq -r .id)
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": "Hello Blitframe"}).json()
project_id = project["id"]
const api = process.env.BLITFRAME;
const headers = { Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}` };
const json = { ...headers, "Content-Type": "application/json" };

const project = await (
  await fetch(`${api}/projects`, { method: "POST", headers: json, body: JSON.stringify({ name: "Hello Blitframe" }) })
).json();
const projectId = project.id;
<?php
function call(string $method, string $path, ?array $body = null, array $headers = []): array {
    $headers[] = "Authorization: Bearer " . getenv("BLITFRAME_API_KEY");
    $ch = curl_init(getenv("BLITFRAME") . $path);
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => $method]);
    if ($body !== null) {
        $headers[] = "Content-Type: application/json";
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    return json_decode(curl_exec($ch), true);
}

$project = call("POST", "/projects", ["name" => "Hello Blitframe"]);
$projectId = $project["id"];
require "net/http"
require "json"

def call(method, path, body = nil, headers = {})
  uri = URI(ENV["BLITFRAME"] + path)
  headers = { "Authorization" => "Bearer #{ENV["BLITFRAME_API_KEY"]}" }.merge(headers)
  headers["Content-Type"] = "application/json" if body
  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: "Hello Blitframe" })
project_id = project["id"]
package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func call(method, path string, body any, headers map[string]string) map[string]any {
	var payload bytes.Buffer
	if body != nil {
		if err := json.NewEncoder(&payload).Encode(body); err != nil {
			panic(err)
		}
	}
	req, err := http.NewRequest(method, os.Getenv("BLITFRAME")+path, &payload)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BLITFRAME_API_KEY"))
	if body != nil {
		req.Header.Set("Content-Type", "application/json")
	}
	for name, value := range headers {
		req.Header.Set(name, value)
	}
	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": "Hello Blitframe"}, nil)
	projectID := project["id"].(string)
	_ = projectID // the next step uses it
}
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 = null, params (string Name, string Value)[] headers)
{
    var request = new HttpRequestMessage(method, api + path);
    if (body != null) request.Content = JsonContent.Create(body);
    foreach (var (name, value) in headers) request.Headers.Add(name, value);
    var response = await http.SendAsync(request);
    return (await response.Content.ReadFromJsonAsync<JsonNode>())!;
}

var project = await call(HttpMethod.Post, "/projects", new { name = "Hello Blitframe" });
var projectId = project["id"]!.GetValue<string>();
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;

public class Example {
    static final ObjectMapper json = new ObjectMapper();

    static JsonNode call(String method, String path, String body, String... headers) throws Exception {
        HttpRequest.Builder request = HttpRequest.newBuilder(URI.create(System.getenv("BLITFRAME") + path))
            .header("Authorization", "Bearer " + System.getenv("BLITFRAME_API_KEY"))
            .method(method, body == null ? HttpRequest.BodyPublishers.noBody() : HttpRequest.BodyPublishers.ofString(body));
        if (body != null) request.header("Content-Type", "application/json");
        if (headers.length > 0) request.headers(headers);
        HttpResponse<String> response = HttpClient.newHttpClient().send(request.build(), HttpResponse.BodyHandlers.ofString());
        return json.readTree(response.body());
    }

    public static void main(String[] args) throws Exception {
        JsonNode project = call("POST", "/projects", """
            {"name": "Hello Blitframe"}
            """);
        String projectId = project.get("id").asText();
    }
}

The response is the new, empty project, with more fields than these. Its id is now in PROJECT_ID (project_id, projectId or projectID in the other languages). Its headVersionId, the id of its head, is null until you add a version:

{
  "id": "6f1c…",
  "name": "Hello Blitframe",
  "headVersionId": null,
  "renderable": null
}

3. Add a composition

An edit sends files to a project and saves them as a new version, which becomes the head. This edit sends one file, data.json: a sample composition of a blue rounded plate on a dark background, 3 seconds long at 1280×720.

COMPOSITION=$(cat <<'JSON'
{"v": "5.12.2", "nm": "Hello Blitframe", "fr": 30, "ip": 0, "op": 90, "w": 1280, "h": 720, "ddd": 0, "assets": [],
 "layers": [
   {"ty": 4, "ind": 1, "nm": "Plate", "ip": 0, "op": 90, "st": 0, "sr": 1,
    "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [640, 360, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
           "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
    "shapes": [{"ty": "gr", "nm": "Plate", "it": [
      {"ty": "rc", "d": 1, "p": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [800, 300]}, "r": {"a": 0, "k": 32}},
      {"ty": "fl", "c": {"a": 0, "k": [0.1, 0.3, 0.8, 1]}, "o": {"a": 0, "k": 100}, "r": 1},
      {"ty": "tr", "p": {"a": 0, "k": [0, 0]}, "a": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [100, 100]},
       "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}}]}]},
   {"ty": 1, "ind": 2, "nm": "Background", "ip": 0, "op": 90, "st": 0, "sr": 1,
    "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [0, 0, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
           "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
    "sw": 1280, "sh": 720, "sc": "#101725"}]}
JSON
)

VERSION=$(jq -n --arg content "$COMPOSITION" \
    '{message: "First version", files: [{path: "data.json", content: $content}]}' \
  | curl -s -X POST $BLITFRAME/projects/$PROJECT_ID/versions \
    -H "Authorization: Bearer $BLITFRAME_API_KEY" \
    -H "Content-Type: application/json" \
    -d @-)
echo "$VERSION" | jq '{renderable, problems}'
composition = """
{"v": "5.12.2", "nm": "Hello Blitframe", "fr": 30, "ip": 0, "op": 90, "w": 1280, "h": 720, "ddd": 0, "assets": [],
 "layers": [
   {"ty": 4, "ind": 1, "nm": "Plate", "ip": 0, "op": 90, "st": 0, "sr": 1,
    "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [640, 360, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
           "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
    "shapes": [{"ty": "gr", "nm": "Plate", "it": [
      {"ty": "rc", "d": 1, "p": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [800, 300]}, "r": {"a": 0, "k": 32}},
      {"ty": "fl", "c": {"a": 0, "k": [0.1, 0.3, 0.8, 1]}, "o": {"a": 0, "k": 100}, "r": 1},
      {"ty": "tr", "p": {"a": 0, "k": [0, 0]}, "a": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [100, 100]},
       "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}}]}]},
   {"ty": 1, "ind": 2, "nm": "Background", "ip": 0, "op": 90, "st": 0, "sr": 1,
    "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [0, 0, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
           "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
    "sw": 1280, "sh": 720, "sc": "#101725"}]}
"""

version = requests.post(f"{api}/projects/{project_id}/versions", headers=headers, json={
    "message": "First version",
    "files": [{"path": "data.json", "content": composition}],
}).json()
print(version["renderable"], version["problems"])
const composition = `
{"v": "5.12.2", "nm": "Hello Blitframe", "fr": 30, "ip": 0, "op": 90, "w": 1280, "h": 720, "ddd": 0, "assets": [],
 "layers": [
   {"ty": 4, "ind": 1, "nm": "Plate", "ip": 0, "op": 90, "st": 0, "sr": 1,
    "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [640, 360, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
           "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
    "shapes": [{"ty": "gr", "nm": "Plate", "it": [
      {"ty": "rc", "d": 1, "p": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [800, 300]}, "r": {"a": 0, "k": 32}},
      {"ty": "fl", "c": {"a": 0, "k": [0.1, 0.3, 0.8, 1]}, "o": {"a": 0, "k": 100}, "r": 1},
      {"ty": "tr", "p": {"a": 0, "k": [0, 0]}, "a": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [100, 100]},
       "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}}]}]},
   {"ty": 1, "ind": 2, "nm": "Background", "ip": 0, "op": 90, "st": 0, "sr": 1,
    "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [0, 0, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
           "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
    "sw": 1280, "sh": 720, "sc": "#101725"}]}`;

const version = await (
  await fetch(`${api}/projects/${projectId}/versions`, {
    method: "POST",
    headers: json,
    body: JSON.stringify({
      message: "First version",
      files: [{ path: "data.json", content: composition }],
    }),
  })
).json();
console.log(version.renderable, version.problems);
$composition = <<<'JSON'
{"v": "5.12.2", "nm": "Hello Blitframe", "fr": 30, "ip": 0, "op": 90, "w": 1280, "h": 720, "ddd": 0, "assets": [],
 "layers": [
   {"ty": 4, "ind": 1, "nm": "Plate", "ip": 0, "op": 90, "st": 0, "sr": 1,
    "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [640, 360, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
           "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
    "shapes": [{"ty": "gr", "nm": "Plate", "it": [
      {"ty": "rc", "d": 1, "p": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [800, 300]}, "r": {"a": 0, "k": 32}},
      {"ty": "fl", "c": {"a": 0, "k": [0.1, 0.3, 0.8, 1]}, "o": {"a": 0, "k": 100}, "r": 1},
      {"ty": "tr", "p": {"a": 0, "k": [0, 0]}, "a": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [100, 100]},
       "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}}]}]},
   {"ty": 1, "ind": 2, "nm": "Background", "ip": 0, "op": 90, "st": 0, "sr": 1,
    "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [0, 0, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
           "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
    "sw": 1280, "sh": 720, "sc": "#101725"}]}
JSON;

$version = call("POST", "/projects/$projectId/versions", [
    "message" => "First version",
    "files" => [["path" => "data.json", "content" => $composition]],
]);
var_dump($version["renderable"], $version["problems"]);
composition = <<~'JSON'
  {"v": "5.12.2", "nm": "Hello Blitframe", "fr": 30, "ip": 0, "op": 90, "w": 1280, "h": 720, "ddd": 0, "assets": [],
   "layers": [
     {"ty": 4, "ind": 1, "nm": "Plate", "ip": 0, "op": 90, "st": 0, "sr": 1,
      "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [640, 360, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
             "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
      "shapes": [{"ty": "gr", "nm": "Plate", "it": [
        {"ty": "rc", "d": 1, "p": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [800, 300]}, "r": {"a": 0, "k": 32}},
        {"ty": "fl", "c": {"a": 0, "k": [0.1, 0.3, 0.8, 1]}, "o": {"a": 0, "k": 100}, "r": 1},
        {"ty": "tr", "p": {"a": 0, "k": [0, 0]}, "a": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [100, 100]},
         "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}}]}]},
     {"ty": 1, "ind": 2, "nm": "Background", "ip": 0, "op": 90, "st": 0, "sr": 1,
      "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [0, 0, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
             "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
      "sw": 1280, "sh": 720, "sc": "#101725"}]}
JSON

version = call("POST", "/projects/#{project_id}/versions", {
  message: "First version",
  files: [{ path: "data.json", content: composition }],
})
p version["renderable"], version["problems"]
// also import "fmt"
composition := `
{"v": "5.12.2", "nm": "Hello Blitframe", "fr": 30, "ip": 0, "op": 90, "w": 1280, "h": 720, "ddd": 0, "assets": [],
 "layers": [
   {"ty": 4, "ind": 1, "nm": "Plate", "ip": 0, "op": 90, "st": 0, "sr": 1,
    "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [640, 360, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
           "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
    "shapes": [{"ty": "gr", "nm": "Plate", "it": [
      {"ty": "rc", "d": 1, "p": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [800, 300]}, "r": {"a": 0, "k": 32}},
      {"ty": "fl", "c": {"a": 0, "k": [0.1, 0.3, 0.8, 1]}, "o": {"a": 0, "k": 100}, "r": 1},
      {"ty": "tr", "p": {"a": 0, "k": [0, 0]}, "a": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [100, 100]},
       "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}}]}]},
   {"ty": 1, "ind": 2, "nm": "Background", "ip": 0, "op": 90, "st": 0, "sr": 1,
    "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [0, 0, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
           "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
    "sw": 1280, "sh": 720, "sc": "#101725"}]}`

version := call("POST", "/projects/"+projectID+"/versions", map[string]any{
	"message": "First version",
	"files":   []map[string]string{{"path": "data.json", "content": composition}},
}, nil)
fmt.Println(version["renderable"], version["problems"])
var composition = """
    {"v": "5.12.2", "nm": "Hello Blitframe", "fr": 30, "ip": 0, "op": 90, "w": 1280, "h": 720, "ddd": 0, "assets": [],
     "layers": [
       {"ty": 4, "ind": 1, "nm": "Plate", "ip": 0, "op": 90, "st": 0, "sr": 1,
        "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [640, 360, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
               "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
        "shapes": [{"ty": "gr", "nm": "Plate", "it": [
          {"ty": "rc", "d": 1, "p": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [800, 300]}, "r": {"a": 0, "k": 32}},
          {"ty": "fl", "c": {"a": 0, "k": [0.1, 0.3, 0.8, 1]}, "o": {"a": 0, "k": 100}, "r": 1},
          {"ty": "tr", "p": {"a": 0, "k": [0, 0]}, "a": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [100, 100]},
           "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}}]}]},
       {"ty": 1, "ind": 2, "nm": "Background", "ip": 0, "op": 90, "st": 0, "sr": 1,
        "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [0, 0, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
               "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
        "sw": 1280, "sh": 720, "sc": "#101725"}]}
    """;

var version = await call(HttpMethod.Post, $"/projects/{projectId}/versions", new
{
    message = "First version",
    files = new[] { new { path = "data.json", content = composition } },
});
var problems = version["problems"]!.AsArray().Select(p => (string?)p);
Console.WriteLine($"{version["renderable"]} [{string.Join("; ", problems)}]");
String composition = """
    {"v": "5.12.2", "nm": "Hello Blitframe", "fr": 30, "ip": 0, "op": 90, "w": 1280, "h": 720, "ddd": 0, "assets": [],
     "layers": [
       {"ty": 4, "ind": 1, "nm": "Plate", "ip": 0, "op": 90, "st": 0, "sr": 1,
        "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [640, 360, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
               "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
        "shapes": [{"ty": "gr", "nm": "Plate", "it": [
          {"ty": "rc", "d": 1, "p": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [800, 300]}, "r": {"a": 0, "k": 32}},
          {"ty": "fl", "c": {"a": 0, "k": [0.1, 0.3, 0.8, 1]}, "o": {"a": 0, "k": 100}, "r": 1},
          {"ty": "tr", "p": {"a": 0, "k": [0, 0]}, "a": {"a": 0, "k": [0, 0]}, "s": {"a": 0, "k": [100, 100]},
           "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}}]}]},
       {"ty": 1, "ind": 2, "nm": "Background", "ip": 0, "op": 90, "st": 0, "sr": 1,
        "ks": {"a": {"a": 0, "k": [0, 0, 0]}, "p": {"a": 0, "k": [0, 0, 0]}, "s": {"a": 0, "k": [100, 100, 100]},
               "r": {"a": 0, "k": 0}, "o": {"a": 0, "k": 100}},
        "sw": 1280, "sh": 720, "sc": "#101725"}]}
    """;

JsonNode version = call("POST", "/projects/" + projectId + "/versions", """
    {"message": "First version", "files": [{"path": "data.json", "content": %s}]}
    """.formatted(json.writeValueAsString(composition)));
System.out.println(version.get("renderable") + " " + version.get("problems"));

The response is the new version. These two fields say whether it can be rendered:

{ "renderable": true, "problems": [] }

If renderable is false, problems says why, such as a missing font or image.

To send your own export instead, put its data.json in content and add each file it uses (your own composition).

4. Render it

RENDER_ID=$(curl -s -X POST $BLITFRAME/renders \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"'$PROJECT_ID'","format":"mp4"}' | jq -r .id)
render_id = requests.post(f"{api}/renders", headers=headers, json={"projectId": project_id, "format": "mp4"}).json()["id"]
const renderId = (
  await (
    await fetch(`${api}/renders`, { method: "POST", headers: json, body: JSON.stringify({ projectId, format: "mp4" }) })
  ).json()
).id;
$renderId = call("POST", "/renders", ["projectId" => $projectId, "format" => "mp4"])["id"];
render_id = call("POST", "/renders", { projectId: project_id, format: "mp4" })["id"]
renderID := call("POST", "/renders", map[string]any{"projectId": projectID, "format": "mp4"}, nil)["id"].(string)
_ = renderID // the next step uses it
var renderId = (await call(HttpMethod.Post, "/renders", new { projectId, format = "mp4" }))["id"]!.GetValue<string>();
String renderId = call("POST", "/renders", """
    {"projectId": "%s", "format": "mp4"}
    """.formatted(projectId)).get("id").asText();

projectId renders the project's head. The response is the render, with more fields than these. Its id is now in RENDER_ID:

{
  "id": "3c5e…",
  "status": "queued",
  "chargedSeconds": 2
}

The render is charged now: 2 render seconds for this 3-second 720p video. If it fails, they are refunded, with two exceptions (pricing).

5. Download the video

Get the render until it finishes, then save the video. Prefer: wait=50 makes each request wait up to 50 seconds for the render to finish. A webhook can tell you instead.

while :; do
  RENDER=$(curl -s $BLITFRAME/renders/$RENDER_ID \
    -H "Authorization: Bearer $BLITFRAME_API_KEY" \
    -H "Prefer: wait=50")
  STATUS=$(echo "$RENDER" | jq -r .status)
  [ "$STATUS" = queued ] || [ "$STATUS" = rendering ] || break
done

if [ "$STATUS" = succeeded ]; then
  curl -s -o hello.mp4 "$(echo "$RENDER" | jq -r .output.mp4Url)"
  echo "Saved hello.mp4"
else
  echo "$RENDER" | jq '{status, error}'
fi
while True:
    render = requests.get(f"{api}/renders/{render_id}", headers={**headers, "Prefer": "wait=50"}).json()
    if render["status"] not in ("queued", "rendering"):
        break

if render["status"] == "succeeded":
    with open("hello.mp4", "wb") as file:
        file.write(requests.get(render["output"]["mp4Url"]).content)
    print("Saved hello.mp4")
else:
    print(render["status"], render["error"])
import { writeFile } from "node:fs/promises";

let render;
do {
  render = await (await fetch(`${api}/renders/${renderId}`, { headers: { ...headers, Prefer: "wait=50" } })).json();
} while (render.status === "queued" || render.status === "rendering");

if (render.status === "succeeded") {
  const video = await fetch(render.output.mp4Url);
  await writeFile("hello.mp4", Buffer.from(await video.arrayBuffer()));
  console.log("Saved hello.mp4");
} else {
  console.log(render.status, render.error);
}
do {
    $render = call("GET", "/renders/$renderId", headers: ["Prefer: wait=50"]);
} while (in_array($render["status"], ["queued", "rendering"]));

if ($render["status"] === "succeeded") {
    $download = curl_init($render["output"]["mp4Url"]);
    curl_setopt($download, CURLOPT_RETURNTRANSFER, true);
    file_put_contents("hello.mp4", curl_exec($download));
    echo "Saved hello.mp4\n";
} else {
    print_r([$render["status"], $render["error"]]);
}
render = nil
loop do
  render = call("GET", "/renders/#{render_id}", nil, { "Prefer" => "wait=50" })
  break unless %w[queued rendering].include?(render["status"])
end

if render["status"] == "succeeded"
  File.binwrite("hello.mp4", Net::HTTP.get(URI(render["output"]["mp4Url"])))
  puts "Saved hello.mp4"
else
  p render["status"], render["error"]
end
// also import "io"
var render map[string]any
for {
	render = call("GET", "/renders/"+renderID, nil, map[string]string{"Prefer": "wait=50"})
	if render["status"] != "queued" && render["status"] != "rendering" {
		break
	}
}

if render["status"] == "succeeded" {
	video, err := http.Get(render["output"].(map[string]any)["mp4Url"].(string))
	if err != nil {
		panic(err)
	}
	defer video.Body.Close()
	out, err := os.Create("hello.mp4")
	if err != nil {
		panic(err)
	}
	defer out.Close()
	if _, err := io.Copy(out, video.Body); err != nil {
		panic(err)
	}
	fmt.Println("Saved hello.mp4")
} else {
	fmt.Println(render["status"], render["error"])
}
JsonNode render;
do
{
    render = await call(HttpMethod.Get, $"/renders/{renderId}", null, ("Prefer", "wait=50"));
} while ((string)render["status"]! is "queued" or "rendering");

if ((string)render["status"]! == "succeeded")
{
    using var download = new HttpClient();
    await File.WriteAllBytesAsync("hello.mp4", await download.GetByteArrayAsync((string)render["output"]!["mp4Url"]!));
    Console.WriteLine("Saved hello.mp4");
}
else
{
    Console.WriteLine($"{render["status"]} {render["error"]?["code"]}: {render["error"]?["message"]}");
}
// also import java.nio.file.Path
JsonNode render;
String status;
do {
    render = call("GET", "/renders/" + renderId, null, "Prefer", "wait=50");
    status = render.get("status").asText();
} while (status.equals("queued") || status.equals("rendering"));

if (status.equals("succeeded")) {
    HttpRequest download = HttpRequest.newBuilder(URI.create(render.get("output").get("mp4Url").asText())).build();
    HttpClient.newHttpClient().send(download, HttpResponse.BodyHandlers.ofFile(Path.of("hello.mp4")));
    System.out.println("Saved hello.mp4");
} else {
    System.out.println(status + " " + render.get("error"));
}

It prints Saved hello.mp4. Open the file: for 3 seconds it shows a blue rounded plate on a dark background. On the free trial, a small "Made with Blitframe" watermark sits in the bottom-left corner.

The finished render carries the download link in output, with more fields than these:

{
  "status": "succeeded",
  "output": { "mp4Url": "https://…", "expiresAt": "2026-11-04T20:00:00+00:00" }
}

mp4Url is a direct download link, valid for an hour. To get a fresh link, get the render again.

If it didn't work

What you see What to do
401 unauthorized The API key is missing or wrong. Check that BLITFRAME_API_KEY is set in the shell or program that runs the steps.
renderable: false in step 3 Read the version's problems, fix the composition and send the edit again.
422 version_not_renderable in step 4 Read the error message and the version's problems and warnings, fix the composition and send the edit again. An odd width or height shows only in warnings (render refusals).
402 insufficient_render_seconds Your balance is too low, the workspace has no trial, its trial or plan has ended, or a failed payment is still unpaid 3 days after the period ended. The message says which. Choose a plan, or update your card, in Console → This workspace → Plan & billing.
403 plan_limit Your own composition is longer or larger than your plan allows. The free trial renders videos up to 30 seconds long at up to 1280×720 (plan limits).
status is failed error has a code and a message that say why. The render seconds are refunded, with two exceptions (pricing). Background work errors lists each code and what to do.
Step 4 timed out, or no response came The render may have been queued and charged anyway. Check GET /v1/renders?projectId=… before you send it again (retrying).
Step 5 times out Each request can take up to 50 seconds. Give your HTTP client a timeout of at least 60 seconds.

Errors lists every code. If you can't tell what went wrong, report a problem with the render's id.

Next steps

Other ways to start

From After Effects to a video

Export your composition with Blitframe for After Effects, zip the export folder and upload the ZIP as a project. After Effects walks through it, with the requests in the same eight languages (what each language needs). Its requests expect the ZIP to be named summer-sale.zip, and leave the project's id in PROJECT_ID (project_id, projectId or projectID in the other languages). Then continue here at Render it, in the same shell or program.

With a coding agent

Get an API key (step 1), put it in the BLITFRAME_API_KEY environment variable, and paste one prompt into Claude Code, Codex or Cursor. The agent writes a small composition, saves it in a new project and renders it. Build with AI agents has the prompt and explains each step.