# Uploading large files

Send a large file, such as a long video or a whole project as a ZIP, straight to storage. Then use it in an edit, a render or a ZIP import.

Smaller files can go straight into an [edit](/docs/blitframe/projects#editing-a-project), whose request can be up to 64 MB. Files up to 100 MB take one `PUT`. Larger files, up to 8 GB, go up in [parts](#multipart-uploads).

Run the steps in order, in one shell or one file: each step reuses what the one before it set. `BLITFRAME` and `BLITFRAME_API_KEY` are set as in the [quickstart](/docs/blitframe/quickstart#get-an-api-key), and its [Before you start](/docs/blitframe/quickstart#before-you-start) lists what each language needs. In Go and Java, the later steps go inside `main`.

## 1. Create an upload

[`POST /v1/uploads`](/reference/blitframe/uploads/create-an-upload) with the file's name and exact size. The examples upload `background.mp4` from the current folder.

::: code-tabs
```bash
UPLOAD=$(curl -s -X POST $BLITFRAME/uploads \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"background.mp4","sizeBytes":'$(wc -c < background.mp4 | tr -d ' ')'}')
UPLOAD_ID=$(echo "$UPLOAD" | jq -r .id)
UPLOAD_URL=$(echo "$UPLOAD" | jq -r .url)
```
```python
import os, requests

api = os.environ["BLITFRAME"]
headers = {"Authorization": f"Bearer {os.environ['BLITFRAME_API_KEY']}"}

upload = requests.post(f"{api}/uploads", headers=headers,
                       json={"fileName": "background.mp4", "sizeBytes": os.path.getsize("background.mp4")}).json()
upload_id = upload["id"]
upload_url = upload["url"]
```
```javascript
import { readFile, stat } from "node:fs/promises";

const api = process.env.BLITFRAME;
const headers = { Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}` };
const json = { ...headers, "Content-Type": "application/json" };

const upload = await (
  await fetch(`${api}/uploads`, {
    method: "POST",
    headers: json,
    body: JSON.stringify({ fileName: "background.mp4", sizeBytes: (await stat("background.mp4")).size }),
  })
).json();
const uploadId = upload.id;
const uploadUrl = upload.url;
```
```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);
}

$upload = call("POST", "/uploads", ["fileName" => "background.mp4", "sizeBytes" => filesize("background.mp4")]);
$uploadId = $upload["id"];
$uploadUrl = $upload["url"];
```
```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

upload = call("POST", "/uploads", { fileName: "background.mp4", sizeBytes: File.size("background.mp4") })
upload_id = upload["id"]
upload_url = upload["url"]
```
```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() {
	file, err := os.Open("background.mp4")
	if err != nil {
		panic(err)
	}
	info, err := file.Stat()
	if err != nil {
		panic(err)
	}
	upload := call("POST", "/uploads", map[string]any{"fileName": "background.mp4", "sizeBytes": info.Size()}, nil)
	uploadID := upload["id"].(string)
	uploadURL, _ := upload["url"].(string)
	_, _ = uploadID, uploadURL // the next steps use them
}
```
```csharp
using System.Net.Http.Json;
using System.Text.Json.Nodes;

var api = Environment.GetEnvironmentVariable("BLITFRAME");
var http = new HttpClient();

async Task<JsonNode> call(HttpMethod method, string path, object? body = null, params (string Name, string Value)[] headers)
{
    var request = new HttpRequestMessage(method, api + path);
    request.Headers.Authorization = new("Bearer", Environment.GetEnvironmentVariable("BLITFRAME_API_KEY"));
    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 upload = await call(HttpMethod.Post, "/uploads", new { fileName = "background.mp4", sizeBytes = new FileInfo("background.mp4").Length });
var uploadId = upload["id"]!.GetValue<string>();
var uploadUrl = (string?)upload["url"];
```
```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;
import java.nio.file.Files;
import java.nio.file.Path;

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 {
        Path file = Path.of("background.mp4");
        JsonNode upload = call("POST", "/uploads", """
            {"fileName": "background.mp4", "sizeBytes": %d}
            """.formatted(Files.size(file)));
        String uploadId = upload.get("id").asText();
        String uploadUrl = upload.get("url").asText();
    }
}
```
:::

| Field | Description |
|---|---|
| `fileName` | The file's name, up to 255 characters. Its extension must be a [supported file type](#file-capabilities), or `.zip` for a project ZIP. |
| `sizeBytes` | The exact size in bytes, up to 8 GB. A file over its kind's limit, such as a `.png` over 128 MB, or over your plan's [project size](/docs/blitframe/limits#plan-limits), is refused here, before you upload anything. |

The response is `201 Created`. Its `id` is what you later pass as `uploadId` or `zipUploadId`. Up to 100 MB, `url` is where you send the file:

```json
{ "id": "1c9d…", "status": "open", "url": "https://…", "method": "PUT", "expiresAt": "2026-11-04T20:00:00+00:00", "multipart": null, "error": null }
```

Above 100 MB, `url` is `null`, and `multipart` lists one URL per part instead ([multipart uploads](#multipart-uploads)).

## 2. PUT the bytes

::: code-tabs
```bash
curl -s -X PUT --upload-file background.mp4 "$UPLOAD_URL"
```
```python
with open("background.mp4", "rb") as file:
    requests.put(upload_url, data=file)
```
```javascript
await fetch(uploadUrl, { method: "PUT", body: await readFile("background.mp4") });
```
```php
$file = fopen("background.mp4", "rb");
$ch = curl_init($uploadUrl);
curl_setopt_array($ch, [
    CURLOPT_UPLOAD => true,
    CURLOPT_INFILE => $file,
    CURLOPT_INFILESIZE => filesize("background.mp4"),
    CURLOPT_RETURNTRANSFER => true,
]);
curl_exec($ch);
fclose($file);
```
```ruby
uri = URI(upload_url)
request = Net::HTTP::Put.new(uri)
File.open("background.mp4", "rb") do |file|
  request.body_stream = file
  request["Content-Length"] = file.size.to_s
  Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
end
```
```go
req, err := http.NewRequest("PUT", uploadURL, file)
if err != nil {
	panic(err)
}
req.ContentLength = info.Size()
res, err := http.DefaultClient.Do(req)
if err != nil {
	panic(err)
}
res.Body.Close()
```
```csharp
await using var file = File.OpenRead("background.mp4");
await http.PutAsync(uploadUrl, new StreamContent(file));
```
```java
HttpRequest put = HttpRequest.newBuilder(URI.create(uploadUrl))
    .PUT(HttpRequest.BodyPublishers.ofFile(file))
    .build();
HttpClient.newHttpClient().send(put, HttpResponse.BodyHandlers.discarding());
```
:::

Send the file as the raw request body, without an `Authorization` header: the URL is already signed. It accepts exactly `sizeBytes` bytes, and storage refuses a body of any other size.

## 3. Complete it

::: code-tabs
```bash
curl -s -X POST $BLITFRAME/uploads/$UPLOAD_ID/complete \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" \
  -H "Prefer: wait=30" | jq '{status, error}'
```
```python
completed = requests.post(f"{api}/uploads/{upload_id}/complete", headers={**headers, "Prefer": "wait=30"}).json()
print(completed["status"], completed["error"])
```
```javascript
const completed = await (
  await fetch(`${api}/uploads/${uploadId}/complete`, { method: "POST", headers: { ...headers, Prefer: "wait=30" } })
).json();
console.log(completed.status, completed.error);
```
```php
$completed = call("POST", "/uploads/$uploadId/complete", headers: ["Prefer: wait=30"]);
print_r([$completed["status"], $completed["error"]]);
```
```ruby
completed = call("POST", "/uploads/#{upload_id}/complete", nil, { "Prefer" => "wait=30" })
p completed["status"], completed["error"]
```
```go
// also import "fmt"
completed := call("POST", "/uploads/"+uploadID+"/complete", nil, map[string]string{"Prefer": "wait=30"})
fmt.Println(completed["status"], completed["error"])
```
```csharp
var completed = await call(HttpMethod.Post, $"/uploads/{uploadId}/complete", null, ("Prefer", "wait=30"));
Console.WriteLine($"{completed["status"]} {(string?)completed["error"]?["message"] ?? "null"}");
```
```java
JsonNode completed = call("POST", "/uploads/" + uploadId + "/complete", null, "Prefer", "wait=30");
System.out.println(completed.get("status").asText() + " " + completed.get("error"));
```
:::

Complete every upload once its bytes are in place. A single-`PUT` upload needs no body, and a multipart upload lists its parts ([below](#multipart-uploads)). Blitframe then checks the file as an edit would: its type, contents and limits. A font is also prepared for rendering.

`Prefer: wait=30` holds the answer until the upload is `ready` or `failed`, or 30 seconds pass. Without it, the answer comes at once. [`Prefer: wait=N`](/docs/blitframe/renders#waiting-for-a-result) takes up to 50 seconds. The upload's `status` is one of:

| `status` | Meaning |
|---|---|
| `open` | Created, not completed yet. |
| `processing` | Being checked. Most files take seconds. Several gigabytes can take minutes. |
| `ready` | Checked. An edit, render or import can use it. A ZIP is `ready` as soon as it is completed, because its import checks it. |
| `failed` | `error` says why. |

```json
{ "id": "1c9d…", "status": "failed", "url": null, "method": null, "expiresAt": "2026-11-04T20:00:00+00:00", "multipart": null, "error": { "code": "invalid_request", "message": "'background.mp4' is not a valid .mp4 file." } }
```

[`GET /v1/uploads/{uploadId}`](/reference/blitframe/uploads/get-an-upload) returns the upload and takes `Prefer: wait=N` too. Completing again is harmless: it answers with the upload as it is.

If the check failed with `interrupted`, it stopped on Blitframe's side. Complete the upload again to check it again, without sending the bytes again. An upload is checked at most three times: after that it fails with `check_limit`, and you upload the file again. Any other failure is about the file itself and is final, so create a new upload.

## 4. Use it

Each upload can be used once: by an edit, a ZIP import or one render's replacements, including one render of a batch. Use it within 1 hour of creating it, or 24 hours for a multipart upload. After that it expires and is deleted, whether it is `ready` or not ([limits](/docs/blitframe/limits#uploads-and-zip-imports)).

### In an edit

Name the upload as a file of an [edit](/docs/blitframe/projects#editing-a-project) (`POST /v1/projects/{projectId}/versions`):

```json
{ "files": [{ "path": "video/background.mp4", "uploadId": "1c9d…" }] }
```

The path must end in the upload's extension, letter case aside. To add a composition, create its upload with the name `data.json`. The file was already checked, so the edit is quick whatever its size.

An edit takes only `ready` uploads. Otherwise it answers `409 upload_incomplete`, `upload_processing` or `upload_failed` ([refusals](#refusals)).

### In a render

A replacement's new image or video names the upload ([replacements in a render](/docs/blitframe/editing#in-a-render)):

```json
{ "layer": "/layers/3", "file": { "path": "images/product-es.png", "uploadId": "1c9d…" } }
```

A render takes only `ready` uploads too ([when an upload is refused](/docs/blitframe/editing#when-an-upload-is-refused)). Queueing the render holds the upload until the render's version is made.

### As a new project

Upload a ZIP and create the project from it:

```http
POST /v1/projects
{ "name": "Summer ad", "zipUploadId": "1c9d…", "fontLicenseAccepted": true }
```

The ZIP becomes the project's version 1, and its folder structure becomes the file paths.

- Put `data.json` at the root of the ZIP or in a folder. When one `data.json` is shallower than every other, the folder it is in becomes the project's root. Files outside that folder keep their ZIP path. Zipping the folder itself gives you that.
- When two `data.json` files are equally shallow, such as `a/data.json` and `b/data.json`, the ZIP's own root stays the root, so the version has no `data.json` at its root.
- A ZIP without `data.json` still imports. Its version's `problems` say the file is missing, and it can't render until you add one.
- Files your system adds when zipping are skipped: `__MACOSX/`, `.DS_Store`, macOS `._` files, `Thumbs.db` and `desktop.ini`. Every other file must be a supported type.
- A ZIP with font files needs `"fontLicenseAccepted": true` ([fonts](/docs/blitframe/fonts#licensing)).

### Into an existing project

Import a ZIP as the project's next version:

```http
POST /v1/projects/{projectId}/package
{ "zipUploadId": "1c9d…", "expectedHeadVersionId": "b7e2…" }
```

The new version holds exactly the ZIP's files and becomes the head. Files of the head that are not in the ZIP are not carried over. It keeps the head's [soundtrack](/docs/blitframe/projects#soundtrack) while the ZIP still holds that audio file. The ZIP follows the same rules as for a new project, `fontLicenseAccepted` included. The response is `201 Created` with the new version.

The head is `main`'s, or that of the [variation](/docs/blitframe/variations) you name in `"variation"`. `expectedHeadVersionId` is optional. With it, that head must still be that version when the import finishes, or you get `409 head_moved` and the upload stays usable. Without it, the ZIP replaces whatever the head is then.

Send an `Idempotency-Key` header with either request, so a retry after a lost answer can't import the ZIP twice. For 24 hours, a retry with the same key answers like the first request: with the project or version it made, or, if the first answered `202 Accepted`, with the import as it is now. If the first import failed, the retry imports again ([retrying safely](/docs/blitframe/api#retrying-safely)).

### Large ZIPs

An import holds the request for up to 50 seconds, and [`Prefer: wait=N`](/docs/blitframe/renders#waiting-for-a-result) shortens that. If the import finishes in time, you get the new project or version, or the import's error. A project created from a ZIP that fails is not kept. If the ZIP is still importing, you get `202 Accepted` with the import:

```json
{
  "id": "e41c…",
  "projectId": "9a0f…",
  "status": "importing",
  "versionId": null,
  "error": null,
  "createdAt": "2026-11-07T09:30:00+00:00",
  "finishedAt": null
}
```

Get the import with [`GET /v1/projects/{projectId}/package/{importId}`](/reference/blitframe/projects/get-a-zip-import) while `status` is `queued` or `importing`. It takes `Prefer: wait=N` too. It ends `succeeded`, with the new `versionId`, or `failed`, with an `error` (`code` and `message`) as the import request would have answered.

Imports run one at a time per workspace, in the order sent. An import that stops partway fails with `interrupted`: send it again. [Limits](/docs/blitframe/limits#uploads-and-zip-imports) says how many imports can wait. [Import details](#import-details) says what else can make one fail, and [refusals](#refusals) why one is refused.

## Multipart uploads

Above 100 MB, the file goes up in parts of `partSize` bytes (64 MB), and the last part holds the rest. The response to step 1 lists a URL per part:

```json
{
  "id": "7a41…",
  "status": "open",
  "url": null,
  "method": null,
  "expiresAt": "2026-11-05T20:00:00+00:00",
  "multipart": {
    "partSize": 67108864,
    "partCount": 4,
    "urlsExpireAt": "2026-11-04T21:00:00+00:00",
    "parts": [{ "partNumber": 1, "url": "https://…" }, { "partNumber": 2, "url": "https://…" }, …]
  },
  "error": null
}
```

1. `PUT` each part to its URL. Part 1 is bytes `0` to `partSize - 1`, part 2 the next `partSize` bytes, and so on. Each URL accepts exactly its part's size. Parts can go in parallel.
2. Keep the `ETag` header of each `PUT` response.
3. Complete the upload with every part's number and ETag.

The examples continue from [step 1](#create-an-upload), with an upload over 100 MB, in place of steps 2 and 3. Replace the values in `etags` with the ETags you kept, in part order:

::: code-tabs
```bash
curl -s -X POST $BLITFRAME/uploads/$UPLOAD_ID/complete \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parts":[{"partNumber":1,"etag":"\"5d41…\""},{"partNumber":2,"etag":"\"7c2b…\""},{"partNumber":3,"etag":"\"9e10…\""},{"partNumber":4,"etag":"\"0b8f…\""}]}'
```
```python
etags = ['"5d41…"', '"7c2b…"', '"9e10…"', '"0b8f…"']
parts = [{"partNumber": n, "etag": etag} for n, etag in enumerate(etags, start=1)]
completed = requests.post(f"{api}/uploads/{upload_id}/complete", headers=headers, json={"parts": parts}).json()
print(completed["status"], completed["error"])
```
```javascript
const etags = ['"5d41…"', '"7c2b…"', '"9e10…"', '"0b8f…"'];
const parts = etags.map((etag, i) => ({ partNumber: i + 1, etag }));
const completed = await (
  await fetch(`${api}/uploads/${uploadId}/complete`, { method: "POST", headers: json, body: JSON.stringify({ parts }) })
).json();
console.log(completed.status, completed.error);
```
```php
$etags = ['"5d41…"', '"7c2b…"', '"9e10…"', '"0b8f…"'];
$parts = [];
foreach ($etags as $i => $etag) {
    $parts[] = ["partNumber" => $i + 1, "etag" => $etag];
}
$completed = call("POST", "/uploads/$uploadId/complete", ["parts" => $parts]);
print_r([$completed["status"], $completed["error"]]);
```
```ruby
etags = ['"5d41…"', '"7c2b…"', '"9e10…"', '"0b8f…"']
parts = etags.map.with_index(1) { |etag, n| { partNumber: n, etag: etag } }
completed = call("POST", "/uploads/#{upload_id}/complete", { parts: parts })
p completed["status"], completed["error"]
```
```go
// also import "fmt"
etags := []string{`"5d41…"`, `"7c2b…"`, `"9e10…"`, `"0b8f…"`}
parts := []map[string]any{}
for i, etag := range etags {
	parts = append(parts, map[string]any{"partNumber": i + 1, "etag": etag})
}
completed := call("POST", "/uploads/"+uploadID+"/complete", map[string]any{"parts": parts}, nil)
fmt.Println(completed["status"], completed["error"])
```
```csharp
string[] etags = ["\"5d41…\"", "\"7c2b…\"", "\"9e10…\"", "\"0b8f…\""];
var parts = etags.Select((etag, i) => new { partNumber = i + 1, etag });
var completed = await call(HttpMethod.Post, $"/uploads/{uploadId}/complete", new { parts });
Console.WriteLine($"{completed["status"]} {(string?)completed["error"]?["message"] ?? "null"}");
```
```java
String[] etags = {"\"5d41…\"", "\"7c2b…\"", "\"9e10…\"", "\"0b8f…\""};
var parts = json.createArrayNode();
for (int i = 0; i < etags.length; i++) {
    parts.addObject().put("partNumber", i + 1).put("etag", etags[i]);
}
JsonNode completed = call("POST", "/uploads/" + uploadId + "/complete", json.createObjectNode().set("parts", parts).toString());
System.out.println(completed.get("status").asText() + " " + completed.get("error"));
```
:::

The response is the upload, checked as in [step 3](#complete-it). If the completion leaves out a part, it is refused and the upload stays open. Upload the missing parts and complete it again.

Part URLs last 1 hour, and the upload stays open for 24 hours. To resume after the URLs expired, get fresh ones with `POST /v1/uploads/{uploadId}/parts`. Then upload only the parts you are missing:

```http
POST /v1/uploads/7a41…/parts
{ "partNumbers": [3, 4] }
```

Leave out `partNumbers`, or send no body, to get every part again. The response is the `multipart` object above.

Browser code can upload parts directly: the upload URLs accept cross-origin `PUT` requests and expose the `ETag` response header.

## Delete an upload

[`DELETE /v1/uploads/{uploadId}`](/reference/blitframe/uploads/abort-an-upload) deletes an upload you no longer need. It also discards the parts of an open multipart upload. A workspace can hold 100 unexpired uploads. Delete the ones you won't use, or let them expire ([which uploads count](/docs/blitframe/limits#uploads-and-zip-imports)).

## Copy files from another version

Add a file that is already in any version of your workspace, in any project, to an edit without uploading it:

```json
{ "files": [{ "path": "images/logo.png", "fromVersionId": "4f0a…", "fromPath": "brand/logo.png" }] }
```

`fromPath` defaults to `path`. The file type must stay the same: a `.png` can't become a `.jpg`. The composition, the `data.json` at the root, can only be copied from another version's root `data.json`.

To turn another JSON file into the composition, send its content or an upload named `data.json`. To keep a copy of the composition at another path, send its content or an upload with any other `.json` name. An upload named `data.json` is always the composition.

To find files to reuse, list a project's files with `GET /v1/projects/{projectId}/files` ([project files](/docs/blitframe/projects#project-files)).

## File capabilities

[`GET /v1/files/capabilities`](/reference/blitframe/uploads/get-file-capabilities) returns every supported file extension with its limits, and the upload, ZIP and edit limits. `maxInlineEditBytes` is the largest edit request body. Use it for file pickers and to check a file before you upload it. The server still checks every file. You can cache the answer for 5 minutes.

```json
{
  "upload": { "maxSizeBytes": 8589934592, "singlePutMaxBytes": 104857600, "multipartPartSizeBytes": 67108864, "singleUploadLifetimeSeconds": 3600, "multipartUploadLifetimeSeconds": 86400, "partUrlLifetimeSeconds": 3600 },
  "zip": { "maxFiles": 5000, "maxUncompressedBytes": 8589934592, "maxCompressionRatio": 200 },
  "maxFilesPerVersion": 5000,
  "maxInlineEditBytes": 67108864,
  "compositionPath": "data.json",
  "textFittingPath": "text_fitting.json",
  "files": [
    { "extension": ".mp4", "kind": "video", "contentType": "video/mp4", "maxSizeBytes": 4294967296, "defaultFolder": "videos/", "maxWidth": 8192, "maxHeight": 8192, "maxDurationSeconds": 3600, "fontLicenseRequired": false },
    { "extension": ".png", "kind": "image", "contentType": "image/png", "maxSizeBytes": 134217728, "defaultFolder": "images/", "maxWidth": 8192, "maxHeight": 8192, "maxDurationSeconds": 3600, "fontLicenseRequired": false },
    { "extension": ".ttf", "kind": "font", "contentType": "font/ttf", "maxSizeBytes": 67108864, "defaultFolder": "fonts/", "maxWidth": null, "maxHeight": null, "maxDurationSeconds": null, "fontLicenseRequired": true },
    …
  ]
}
```

`defaultFolder` is a suggestion: any valid path works. `fontLicenseRequired` marks the font types, which need `fontLicenseAccepted: true` when added. On images, `maxDurationSeconds` applies to animated GIF and WebP.

## Details

### Refusals

A refused edit or import changes nothing.

| Request | Answer | When |
|---|---|---|
| Create | `400 invalid_request` | `fileName` is missing, over 255 characters, or not a supported file type or `.zip`. Or `sizeBytes` is not between 1 byte and 8 GB. |
| Create | `413 too_large` | `sizeBytes` is over the limit for the file's kind, such as a `.png` over 128 MB ([file capabilities](#file-capabilities)). |
| Create | `403 project_too_large` | `sizeBytes` is over your plan's [project size](/docs/blitframe/limits#plan-limits), for a file other than a ZIP. A ZIP is checked when it is imported, and refused here only when it is too large to import over any head of your workspace. |
| Create | `409 upload_limit` | The workspace already holds 100 unexpired uploads ([delete an upload](#delete-an-upload)). |
| Create, complete, edit or import | `402 insufficient_render_seconds` or `402 payment_disputed` | The workspace can't render: it has no free trial, its trial or plan has ended, a failed payment is unpaid, or a payment is disputed. It can't add files either until that is fixed, and a completed upload fails with the same error. Running out of render seconds alone doesn't stop uploads. Reading, downloading, exporting and deleting still work. |
| Complete | `400 invalid_request` | The bytes are missing, or not the declared size. |
| Complete a multipart upload | `400 invalid_request` | `parts` does not list each part once, with its ETag. The upload stays open: upload the missing parts and complete it again. |
| Edit | `400 invalid_request` | The upload does not exist, belongs to another workspace or has expired. Or a different request already used it ([edits that name uploads](/docs/blitframe/projects#edits-that-name-uploads)). |
| Edit | `404 not_found` | A file's `fromVersionId` doesn't exist or belongs to another workspace. |
| Edit | `400 invalid_request` | The `fromVersionId` has no file at `fromPath`, or the copy changes the file's type. |
| Edit | `400 invalid_request` | The path does not end in the upload's extension. Or the upload was created as `data.json` and the path is another one, or the other way round. |
| Edit or import | `409 upload_incomplete` | The upload has not been completed. |
| Edit | `409 upload_processing` | The upload is still being checked. The message names every upload of the edit still being checked, and the `Retry-After` header says when to try again. |
| Edit | `409 upload_failed` | The upload failed its check. The message gives the upload's own error code and message. |
| Import | `400 invalid_request` | The upload does not exist, belongs to another workspace, has expired, is not a `.zip`, or was created more than 46 hours ago. |
| Import | `404 not_found` | The project has no such `variation`. |
| Edit or import | `403 project_too_large` | The version's files would total more than your plan's [project size](/docs/blitframe/limits#plan-limits). A ZIP is refused on its upload's size, before it is read, when it could not fit over the head it replaces, and otherwise on the sizes its file list declares, before its files are read. |
| Import | `409 head_moved` | `expectedHeadVersionId` is no longer the head when the import finishes. The upload stays usable. |
| Import | `409 import_limit` | 10 imports are already waiting or running. |

A render that names an upload is refused in the same ways ([when an upload is refused](/docs/blitframe/editing#when-an-upload-is-refused)).

### Import details

Queueing an import extends its upload's expiry to a day from then, but never past 47 hours after the upload was created. An import that waited until its upload has less than an hour left fails with `invalid_request` when it starts. So does an import whose upload was deleted while it waited. Upload the ZIP again in either case.

A finished import's status is kept for 7 days. After that, getting it returns `404`.
