Quickstart
View as MarkdownGo 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
- Change something and render again: edit the project with only the files that change.
- Make one video per row of a data sheet: many videos from a data sheet.
- Set
"format": "hls"for streaming, or"frames"for still images: Renders. - Check what renders before you design: After Effects support.
- Run the whole flow as one program: Code examples.
- Let an AI agent do it: MCP for agents.
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.