# Quickstart

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](#other-ways-to-start).

## Before you start

Your language needs:

| Language | What it needs |
|---|---|
| curl | [jq](https://jqlang.org), to build request bodies and read responses |
| Python | [requests](https://pypi.org/project/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](https://github.com/FasterXML/jackson-databind) 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](/docs/blitframe/concepts) explains the terms on the way: project, version, head and render.

## 1. Get an API key

[Create a Code Artworks account](https://app.codeartworks.com/signup?product=blitframe) 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:

```bash
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](/docs/blitframe/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

::: code-tabs
```bash
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)
```
```python
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"]
```
```javascript
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
<?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"];
```
```ruby
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"]
```
```go
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
}
```
```csharp
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>();
```
```java
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:

```json
{
  "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.

::: code-tabs
```bash
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}'
```
```python
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"])
```
```javascript
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);
```
```php
$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"]);
```
```ruby
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"]
```
```go
// 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"])
```
```csharp
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)}]");
```
```java
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:

```json
{ "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](/docs/blitframe/examples#adapting-the-examples)).

## 4. Render it

::: code-tabs
```bash
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)
```
```python
render_id = requests.post(f"{api}/renders", headers=headers, json={"projectId": project_id, "format": "mp4"}).json()["id"]
```
```javascript
const renderId = (
  await (
    await fetch(`${api}/renders`, { method: "POST", headers: json, body: JSON.stringify({ projectId, format: "mp4" }) })
  ).json()
).id;
```
```php
$renderId = call("POST", "/renders", ["projectId" => $projectId, "format" => "mp4"])["id"];
```
```ruby
render_id = call("POST", "/renders", { projectId: project_id, format: "mp4" })["id"]
```
```go
renderID := call("POST", "/renders", map[string]any{"projectId": projectID, "format": "mp4"}, nil)["id"].(string)
_ = renderID // the next step uses it
```
```csharp
var renderId = (await call(HttpMethod.Post, "/renders", new { projectId, format = "mp4" }))["id"]!.GetValue<string>();
```
```java
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`:

```json
{
  "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](/docs/blitframe/renders#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](/docs/blitframe/webhooks) can tell you instead.

::: code-tabs
```bash
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
```
```python
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"])
```
```javascript
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);
}
```
```php
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"]]);
}
```
```ruby
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
```
```go
// 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"])
}
```
```csharp
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"]}");
}
```
```java
// 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:

```json
{
  "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](/docs/blitframe/errors#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](/docs/blitframe/renders#plan-limits)). |
| `status` is `failed` | `error` has a `code` and a `message` that say why. The render seconds are refunded, with two exceptions ([pricing](/docs/blitframe/renders#pricing)). [Background work errors](/docs/blitframe/errors#background-work) 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](/docs/blitframe/errors#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](/docs/blitframe/errors) lists every code. If you can't tell what went wrong, [report a problem](/docs/blitframe/renders#report-a-problem) with the render's id.

## Next steps

- Change something and render again: [edit the project](/docs/blitframe/projects#editing-a-project) with only the files that change.
- Make one video per row of a data sheet: [many videos from a data sheet](/docs/blitframe/editing#many-videos-from-a-data-sheet).
- Set `"format": "hls"` for streaming, or `"frames"` for still images: [Renders](/docs/blitframe/renders).
- Check what renders before you design: [After Effects support](/docs/blitframe/after-effects-support).
- Run the whole flow as one program: [Code examples](/docs/blitframe/examples).
- Let an AI agent do it: [MCP for agents](/docs/blitframe/mcp).

## 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](/docs/blitframe/after-effects) walks through it, with the requests in the same eight languages ([what each language needs](#before-you-start)). 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](#render-it), in the same shell or program.

### With a coding agent

Get an API key ([step 1](#get-an-api-key)), 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](/docs/blitframe/ai-agents#start-with-one-prompt) has the prompt and explains each step.
