# Renders

A render turns one version of a project into a video (MP4 or HLS) or a set of still frames. This page shows how to start a render, follow it, download the result and cancel it.

## Render a project

The examples read `BLITFRAME`, `BLITFRAME_API_KEY` and `PROJECT_ID` from the environment. Set the first two as in the [quickstart](/docs/blitframe/quickstart#get-an-api-key), and `PROJECT_ID` to the id of a project that has a version.

::: 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\"}" | jq -r .id)

curl -s $BLITFRAME/renders/$RENDER_ID -H "Authorization: Bearer $BLITFRAME_API_KEY" -H "Prefer: wait=50" \
  | jq '{status, mp4Url: .output.mp4Url}'
```
```python
import os, requests

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

render_id = requests.post(f"{api}/renders", headers=headers, json={"projectId": project_id}).json()["id"]

render = requests.get(f"{api}/renders/{render_id}", headers={**headers, "Prefer": "wait=50"}).json()
print(render["status"], (render["output"] or {}).get("mp4Url"))
```
```javascript
const api = process.env.BLITFRAME;
const headers = { Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}` };
const json = { ...headers, "Content-Type": "application/json" };
const projectId = process.env.PROJECT_ID;

const renderId = (
  await (await fetch(`${api}/renders`, { method: "POST", headers: json, body: JSON.stringify({ projectId }) })).json()
).id;

const render = await (await fetch(`${api}/renders/${renderId}`, { headers: { ...headers, Prefer: "wait=50" } })).json();
console.log(render.status, render.output?.mp4Url ?? null);
```
```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);
}

$projectId = getenv("PROJECT_ID");
$renderId = call("POST", "/renders", ["projectId" => $projectId])["id"];

$render = call("GET", "/renders/$renderId", null, ["Prefer: wait=50"]);
echo $render["status"], " ", $render["output"]["mp4Url"] ?? "null", "\n";
```
```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_id = ENV["PROJECT_ID"]
render_id = call("POST", "/renders", { projectId: project_id })["id"]

render = call("GET", "/renders/#{render_id}", nil, { "Prefer" => "wait=50" })
p render["status"], render.dig("output", "mp4Url")
```
```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"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() {
	projectID := os.Getenv("PROJECT_ID")
	renderID := call("POST", "/renders", map[string]any{"projectId": projectID}, nil)["id"].(string)

	render := call("GET", "/renders/"+renderID, nil, map[string]string{"Prefer": "wait=50"})
	output, _ := render["output"].(map[string]any)
	fmt.Println(render["status"], output["mp4Url"])
}
```
```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 projectId = Environment.GetEnvironmentVariable("PROJECT_ID");
var renderId = (await call(HttpMethod.Post, "/renders", new { projectId }))["id"]!.GetValue<string>();

var render = await call(HttpMethod.Get, $"/renders/{renderId}", null, ("Prefer", "wait=50"));
Console.WriteLine($"{render["status"]} {(string?)render["output"]?["mp4Url"] ?? "null"}");
```
```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 {
        String projectId = System.getenv("PROJECT_ID");
        String renderId = call("POST", "/renders", """
            {"projectId": "%s"}
            """.formatted(projectId)).get("id").asText();

        JsonNode render = call("GET", "/renders/" + renderId, null, "Prefer", "wait=50");
        System.out.println(render.get("status").asText() + " " + render.path("output").path("mp4Url").asText("null"));
    }
}
```
:::

The first request queues an MP4 of the project's head. The second waits up to 50 seconds for it to finish, then prints its `status` and download link. Once `status` is `succeeded`, `output.mp4Url` downloads the video. While it is still `queued` or `rendering`, the link is `null`: send the second request again.

A render pins one version: the project's head when you queue it, or a version you name. Later edits never change a render that is queued or running. A render can also carry its own [replacements](#render-with-replacements), such as new text or images for one video, without changing the project. Blitframe renders it on a GPU and charges it in [render seconds](#pricing).

## Create a render

[`POST /v1/renders`](/reference/blitframe/renders/create-a-render) queues one render:

```json
{
  "projectId": "9a0f…",
  "format": "mp4",
  "quality": "high",
  "audio": { "path": "audio/music.mp3", "offsetSeconds": 0 },
  "name": "Summer teaser"
}
```

| Field | Values | Default |
|---|---|---|
| `projectId` | Render the project's head as it is when the render is queued: `main`'s, or that of `variation`. | send this or `versionId` |
| `variation` | With `projectId`: the [variation](/docs/blitframe/variations) whose head to render. | `main` |
| `versionId` | Render this exact version, of any of your projects. | send this or `projectId` |
| `format` | `mp4`, `hls` or `frames` | `mp4` |
| `quality` | `low`, `medium`, `high` or `extraHigh` ([bitrates](#quality)) | `high` |
| `codec` | Only for `mp4` and `hls`: `h264`, `hevc` (H.265) or `av1`. HEVC and AV1 are smaller at the same quality but play on fewer devices and browsers, and [HTML5 ads](#html5-ads) need `h264`. `hevc` and `av1` need a plan with advanced encoding. | `h264` |
| `encoding` | Only for `mp4` and `hls`, on a plan with advanced encoding: your own bitrate, keyframe interval and H.264 profile ([encoding settings](#encoding-settings)). | the [quality](#quality) level's |
| `frames` | Only for `frames`, and required there: `{ "start": 0, "end": 30, "format": "png" }`. `end` is the frame after the last, so `start: 60, end: 61` renders frame 60 alone. `format` is `png`, `jpeg` or `tga` ([frame renders](#frame-renders)). | — |
| `audio` | An audio file in the version (`path`), and where in the video it starts (`offsetSeconds`, 0 to 3,600). It plays from its beginning, stops where the video ends, and replaces the version's `soundtrack`. Frame renders ignore it. | the version's `soundtrack`, if any |
| `replacements` | Text, fonts, images or video to change by layer, for this render only ([render with replacements](#render-with-replacements)). | none |
| `name` | The MP4's [download file name](#download-file-names), up to 200 characters. | project and version names |

Send exactly one of `projectId` and `versionId`. The version must be `renderable`. A refused request is never charged, and [render refusals](/docs/blitframe/errors#render-refusals) lists the reasons.

The response is `202 Accepted` with the render in status `queued`. Its render seconds are [charged](#pricing) now:

```json
{
  "id": "3c5e…",
  "projectId": "9a0f…",
  "versionId": "b7e2…",
  "sourceVersionId": "b7e2…",
  "format": "mp4",
  "quality": "high",
  "frames": null,
  "audio": { "path": "audio/music.mp3", "offsetSeconds": 0 },
  "status": "queued",
  "error": null,
  "chargedSeconds": 15,
  "refundedSeconds": 0,
  "createdAt": "2026-11-04T14:00:00+00:00",
  "startedAt": null,
  "finishedAt": null,
  "output": null,
  "name": "Summer teaser",
  "playback": "preparing"
}
```

| Field | Meaning |
|---|---|
| `id` | The render's id. |
| `sourceVersionId` | The version the request pinned: the `versionId` you sent, or the head when you sent `projectId`. |
| `versionId` | The version rendered. Without replacements it is `sourceVersionId`. With them it is the version made with the replacements, `null` until it is made. When they change nothing, it is `sourceVersionId`. |
| `status` | `queued`, `rendering`, `succeeded`, `failed` or `cancelled` ([check status](#check-status-and-download)) |
| `error` | Why a failed render failed: a `code` and a `message`. Otherwise `null`. |
| `chargedSeconds`, `refundedSeconds` | Render seconds charged when the render was queued, and refunded when it failed or was cancelled. `refundedSeconds` is what came back to your balance: `0` when it succeeded or was not refunded, and less than the charge when your balance was already at the month's allowance ([pricing](#pricing)). |
| `output` | The download links, once there are any ([download the output](#download-the-output)). |
| `playback` | Whether a video can be watched yet: `preparing`, `streaming` (an HLS render [still rendering](#live-hls)) or `complete` (succeeded, every link ready). It is `null` for frame renders and for renders that failed or were cancelled. |
| `replacements` | The replacements you sent, left out when there are none. Only this response and `GET /v1/renders/{renderId}` show them. |
| `createdAt`, `startedAt`, `finishedAt` | When the render was queued, started and finished. |
| `projectId` | The project of the version rendered. |
| `format`, `quality` | As requested, or the defaults. |
| `codec` | The video codec of an `mp4` or `hls` render: `h264`, `hevc` or `av1`. Left out for frame renders. |
| `encoding` | The [encoding settings](#encoding-settings) the render asked for. Left out when its quality level set the bitrate. |
| `audio` | The audio the video plays: the requested `audio`, otherwise the version's `soundtrack`. It is `null` for frame renders and when there is neither. |
| `frames`, `name` | As requested, or `null`. |

### Idempotency

Send an `Idempotency-Key: <your unique id>` header to make retries safe. A retry with the same key within 24 hours gets the first render back, with the header `Idempotent-Replayed: true`, and is not charged again.

- A request that names `projectId` is matched to the version its first render pinned. So a retry returns that render even if the head has moved.
- After 24 hours, or once you [delete](#delete-a-render) the render, the same request queues and charges a new render.

[Retrying safely](/docs/blitframe/api#retrying-safely) has the rules every key follows.

## Render with replacements

`replacements` change layers for one render only. The project and its head stay as they are.

```json
{
  "projectId": "9a0f…",
  "replacements": [
    { "layer": "/layers/0", "text": "Rebajas de verano" },
    { "layer": "/layers/3", "file": { "path": "images/product-es.png", "uploadId": "1c9d…" } }
  ]
}
```

- The render pins a version as usual, and `sourceVersionId` says which.
- Blitframe then makes the render's own version, with the replacements applied. Until it is made, usually within seconds, the render is `queued` and its `versionId` is `null`.
- To reproduce the video, render that `versionId` again without replacements.

A new image or video comes from an [upload](/docs/blitframe/uploads), named by its `uploadId`. [Replacements in a render](/docs/blitframe/editing#in-a-render) has the full rules: what a replacement can change, how text is fitted, and when one is refused.

## Batch renders

[`POST /v1/projects/{projectId}/renders/batch`](/reference/blitframe/renders/create-a-batch-of-renders) queues up to 1,000 renders of one version in one call, such as one video per row of a [data sheet](/docs/blitframe/editing#many-videos-from-a-data-sheet).

```json
{
  "versionId": "b7e2…",
  "renders": [
    { "format": "mp4", "name": "Spanish", "replacements": [{ "layer": "/layers/0", "text": "Rebajas de verano" }] },
    { "format": "mp4", "name": "French", "replacements": [{ "layer": "/layers/0", "text": "Soldes d'été" }] },
    { "format": "frames", "frames": { "start": 0, "end": 1, "format": "jpeg" } }
  ]
}
```

- Every render uses one version: `versionId`, a version of this project, or without it the head of `main` or of `variation`. Edits made while the batch runs never mix into it.
- Each item takes the fields of a single render except `projectId`, `variation` and `versionId`. Its `audio.path` must be in the batch's version.
- The batch is all or nothing. If one item is refused, nothing is queued or charged, and the message starts with the item, such as `renders[1]: …`.
- Each render costs what it would alone, charged together. Each failed or cancelled render is refunded on its own.

The response is `202 Accepted` with `{ "versionId": "…", "renders": [ … ] }`: the pinned version, and the queued renders in the order you sent them, without their `replacements`. [Queue order](#queue-order) says which renders start first.

An `Idempotency-Key` works as for a [single render](#idempotency), except that a batch's key is freed only once all its renders are deleted. Until then, sending the same batch after deleting some of its renders gets `422 idempotency_key_reused` ([retrying safely](/docs/blitframe/api#retrying-safely)).

## Check status and download

[`GET /v1/renders/{renderId}`](/reference/blitframe/renders/get-a-render) returns the render. Its `status` is one of:

| `status` | Meaning |
|---|---|
| `queued` | Waiting for a GPU. A render with replacements first waits for its version to be made. |
| `rendering` | Rendering now. |
| `succeeded` | Done. `output` has the download links. |
| `failed` | `error.code` says why. [Background work errors](/docs/blitframe/errors#background-work) lists each code and what to do. |
| `cancelled` | [Cancelled](#cancel). |

A failed or cancelled render is refunded, with two exceptions ([pricing](#pricing)). To follow a render, [wait for the result](#waiting-for-a-result), poll every few seconds, or use [webhooks](/docs/blitframe/webhooks).

### Waiting for a result

Send a `Prefer: wait=N` header ([RFC 7240](https://www.rfc-editor.org/rfc/rfc7240)) with `GET /v1/renders/{renderId}`. The server holds its response until the render is `succeeded`, `failed` or `cancelled`, or until `N` seconds pass. `N` is at most 50, and larger values count as 50. The `Preference-Applied: wait=N` header says how long the server was willing to wait. If the render is still running, send the request again.

The same header works for [download archives](#download-many-videos-as-one-zip), [version exports](/docs/blitframe/projects#exporting-a-version), [ZIP imports](/docs/blitframe/uploads#large-zips) and [uploads](/docs/blitframe/uploads).

### Download the output

A succeeded HLS render's `output`:

```json
"output": {
  "mp4Url": "https://…",
  "hlsUrl": "https://blitframe.codeartworks.com/v1/renders/…/hls/playlist.m3u8?token=…",
  "frameUrls": null,
  "posterUrl": "https://…/poster.jpg",
  "expiresAt": "2026-11-04T20:00:00+00:00"
}
```

Which links are set depends on the format. The others are `null`:

| Format | Links |
|---|---|
| `mp4` | `mp4Url` and `posterUrl` |
| `hls` | `hlsUrl`, an HLS playlist for players such as hls.js, Safari or ExoPlayer, plus `mp4Url` and `posterUrl` |
| `frames` | `frameUrls`, one per frame, in order, such as `https://…/frame_000000.png` |

Links last an hour, until `expiresAt`. Get the render again for fresh ones. `posterUrl` is the video's [poster](#posters).

### Many renders at once

[`POST /v1/renders/statuses`](/reference/blitframe/renders/get-many-render-statuses) with `{ "renderIds": ["…", "…"] }` returns up to 1,000 renders in one call. The response is `{ "renders": [ … ], "notFound": ["…"] }`: the renders in the order you asked, and the ids that are not your renders or were deleted.

[`GET /v1/renders?projectId=…&limit=50`](/reference/blitframe/renders/list-renders) lists recent renders, newest first. `projectId` is optional, and `limit` goes up to 1,000. Pass `next` as `before` for the next page.

Lists and statuses send `frameUrls` as `null` and leave `replacements` out: get the render to see them.

## Download many videos as one ZIP

[`POST /v1/renders/download-archive`](/reference/blitframe/renders/create-a-download-archive) with `{ "renderIds": ["…", "…"], "name": "Summer campaign" }` packs up to 1,000 succeeded MP4 or HLS renders into one ZIP. The response is `202 Accepted` with the archive in status `queued`.

Get it with [`GET /v1/renders/download-archive/{archiveId}`](/reference/blitframe/renders/get-a-download-archive), which takes [`Prefer: wait=N`](#waiting-for-a-result). Its `status` turns `building`, then `ready`, when `url` downloads the ZIP, or `failed`, when `error` says why:

```json
{
  "id": "…",
  "status": "ready",
  "renderIds": ["…", "…"],
  "fileName": "Summer campaign.zip",
  "url": "https://…",
  "sizeBytes": 48211933,
  "error": null,
  "createdAt": "2026-11-05T20:00:00+00:00",
  "finishedAt": "2026-11-05T20:00:09+00:00",
  "expiresAt": "2026-11-06T20:00:00+00:00"
}
```

Each video is stored under its [download file name](#download-file-names). A repeated name becomes `name (2).mp4`, `name (3).mp4` and so on. `fileName` comes from `name`, or is `renders.zip`. The `download_archive.ready` and `download_archive.failed` [webhooks](/docs/blitframe/webhooks#events) say when it is done. [Limits](/docs/blitframe/limits#renders) has the archive's size, lifetime and queue limits.

## HTML5 ads

[`GET /v1/renders/{renderId}/html?platform=theTradeDesk&clickUrl=https://example.com`](/reference/blitframe/renders/export-an-html5-ad) wraps a succeeded H.264 MP4 or HLS render as an HTML5 ad. The response is `{ "url": "…" }`: a link to one `index.html` or an `ad.zip`, depending on the platform, that lasts an hour.

| `platform` | You get |
|---|---|
| `generic` (default) | One HTML file with the video embedded. |
| `googleCampaignManager360`, `googleDisplayVideo360` | ZIP for rich media. Set the exit in the campaign. |
| `theTradeDesk` | ZIP with a backup image. The video must be under 1.1 MB (`interaction=video`) or at most 2.2 MB (`tapToContinue`). |
| `adform` | ZIP with a manifest. Requires `clickUrl`. |
| `googleAppCampaigns`, `meta`, `tikTok`, `pangle` | Playable ad as a ZIP. |
| `appLovin`, `unityAds` | Playable ad as one HTML file. Requires `clickUrl`. |
| `mintegral`, `moloco`, `liftoff` | Playable ad as one HTML file. |

| Parameter | Values |
|---|---|
| `clickUrl` | An absolute `https://` URL, up to 2,048 characters, without a user name or password. |
| `interaction` | `video` or `tapToContinue`. Playable platforms accept only `tapToContinue`, their default. The others default to `video`. |

The whole ad must be under 5 MB. [Render refusals](/docs/blitframe/errors#render-refusals) lists the other errors.

## Cancel

[`POST /v1/renders/{renderId}/cancel`](/reference/blitframe/renders/cancel-a-render) stops a queued or running render and refunds it. There is no refund for an HLS render that had started streaming, or when your balance was reset since the render was queued ([pricing](#pricing)).

- A queued render is `cancelled` at once.
- A running render comes back still `rendering`. Once its GPU stops, usually within 10 seconds, it turns `cancelled`, with any refund and a `render.cancelled` webhook.

[`POST /v1/renders/cancel`](/reference/blitframe/renders/cancel-many-renders) with `{ "renderIds": [ … ] }` cancels up to 1,000 renders. Its response is like that of [statuses](#many-renders-at-once), with every render as it is now. It leaves finished renders as they are.

Agents use `cancel_render` for one render and `cancel_renders` for many. **Console → Renders** shows a stopping render until it has stopped.

## Delete a render

[`DELETE /v1/renders/{renderId}`](/reference/blitframe/renders/delete-a-render) deletes a finished render and its output files. The response is `204`, and its download links stop working ([deleted renders in archives](#deleted-renders-in-archives)). Deleting does not change your balance. [Cancel](#cancel) a queued or running render first.

## Report a problem

If a render looks wrong, or failed and you can't tell why, tell Blitframe support with [`POST /v1/problem-reports`](/reference/blitframe/problem-reports/report-a-problem).

In the console, open **Support** with the button at the bottom right of any page, or **Report this problem** next to a failed render on the Renders page. We email you to say we got it, and again with the answer. To follow up, reply to either email, or to the request in the Support panel, which keeps the whole conversation.

This example continues the one in [Render a project](#render-a-project), in the same shell or file. It reports the render that example queued, by the id in `RENDER_ID` (`render_id`, `renderId` or `renderID` in the other languages), and reuses its `call` helper. In Go and Java, the lines go at the end of `main`. To report another render, put its id in that variable.

::: code-tabs
```bash
curl -s -X POST $BLITFRAME/problem-reports \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" -H "Content-Type: application/json" \
  -d '{"renderId":"'$RENDER_ID'","message":"The logo flickers between 0:03 and 0:05."}' | jq '{id, status}'
```
```python
report = requests.post(f"{api}/problem-reports", headers=headers, json={
    "renderId": render_id,
    "message": "The logo flickers between 0:03 and 0:05.",
}).json()
print(report["id"], report["status"])
```
```javascript
const report = await (
  await fetch(`${api}/problem-reports`, {
    method: "POST",
    headers: json,
    body: JSON.stringify({ renderId, message: "The logo flickers between 0:03 and 0:05." }),
  })
).json();
console.log(report.id, report.status);
```
```php
$report = call("POST", "/problem-reports", [
    "renderId" => $renderId,
    "message" => "The logo flickers between 0:03 and 0:05.",
]);
echo $report["id"], " ", $report["status"], "\n";
```
```ruby
report = call("POST", "/problem-reports", { renderId: render_id, message: "The logo flickers between 0:03 and 0:05." })
p report["id"], report["status"]
```
```go
report := call("POST", "/problem-reports", map[string]any{
	"renderId": renderID,
	"message":  "The logo flickers between 0:03 and 0:05.",
}, nil)
fmt.Println(report["id"], report["status"])
```
```csharp
var report = await call(HttpMethod.Post, "/problem-reports", new
{
    renderId,
    message = "The logo flickers between 0:03 and 0:05.",
});
Console.WriteLine($"{report["id"]} {report["status"]}");
```
```java
JsonNode report = call("POST", "/problem-reports", """
    {"renderId": "%s", "message": "The logo flickers between 0:03 and 0:05."}
    """.formatted(renderId));
System.out.println(report.get("id").asText() + " " + report.get("status").asText());
```
:::

| Field | Values |
|---|---|
| `message` | What went wrong, up to 2,000 characters. Required. |
| `renderId`, `versionId` | The render or version it concerns. Optional. |

The response is `201 Created` with the report's `id` and `status: "open"`. [`GET /v1/problem-reports/{reportId}`](/reference/blitframe/problem-reports/get-a-problem-report) shows `resolved` once support has replied, with the reply in `resolution`.

The person who sent a report gets an email at once saying we got it, and the reply when it comes. A report sent with an API key gets no such email, and its reply goes to the workspace's owners and admins, as does the reply once the person who sent it has left.

A workspace can send 10 reports an hour. Agents use `report_problem`.

## Pricing

A render costs render seconds: the video's length times a multiplier for its size. The API counts in seconds; the pricing page and the console show render minutes, 60 render seconds each.

| Composition (pixel count up to) | Multiplier |
|---|---|
| 1280×720 | 0.5× |
| 1920×1080 | 1× |
| 2560×1440 | 2× |
| 3840×2160 | 4× |
| larger | 8× |

- A video costs its duration in seconds × the multiplier, rounded up, at least 1. A 15-second 1080p video costs 15 render seconds, and 60 in 4K.
- A frame render costs frames × multiplier ÷ 30, rounded up, at least 1.
- A composition falls in the first row whose pixel count (width × height) it does not exceed.

You are charged when the render is queued. A render that fails or is cancelled is refunded in full, except:

1. An HLS render that had started streaming, since it could already be watched.
2. A render queued before your balance was reset. The new balance replaces the old one, so refunds owed to the old one are dropped. The balance resets when:
   - a new billing period starts: you subscribe or your plan renews
   - a trial or plan runs out
   - a failed payment stays unpaid for 3 days

   Changing plans within a period is not a reset. Moving to a smaller plan within a period takes back the unspent part of what the larger plan added. Seconds held by renders still queued or running count as unspent, so if one of them is then cancelled or fails, its refund is less what was taken back, and `refundedSeconds` says what came back.

A failure on Blitframe's side (`interrupted`, `internal_error` or `stopped_by_support`) is always refunded, into your balance as it is then. If your balance was reset since the render was queued, the refund tops it up only as far as the new period's allowance, and `refundedSeconds` shows only what came back. [Your balance](/docs/blitframe/limits#balance) shows how to read what you have left.

## Plan limits

Your plan can limit how long and how large one render is, and add a small "Made with Blitframe" watermark. The free trial renders videos up to 30 seconds at up to 1280×720, with the watermark. A render over a limit is refused with `403 plan_limit` before anything is charged.

Your plan also sets which codecs and [encoding settings](#encoding-settings) a render can use, whether your renders start ahead in the [queue](#queue-order), and how much your workspace can store. A codec or setting your plan does not include is refused with `403 plan_feature`, and a workspace whose storage is full gets `403 storage_limit`; neither is charged.

[`GET /v1/usage`](/reference/blitframe/workspace/get-usage) shows your limits under `limits`, and every member sees them in **Console → This workspace → Plan & billing**. [Plan limits](/docs/blitframe/limits#plan-limits) explains each one.

## Details

### Frame renders

`frames.end` is at most the composition's frame count, and one render has at most 1,000 frames. Frames come straight from the engine at the composition's size, not from a video. PNG and TGA frames are lossless and keep transparency. JPEG frames have none: transparent areas come out black.

### Quality

`high` follows YouTube's recommended upload bitrates for the composition's size and frame rate. `low` is half of it, `medium` three quarters and `extraHigh` one and a half.

| Composition (pixel count up to) | `high` at up to 30 fps | `high` above 30 fps |
|---|---|---|
| 640×360 | 1 Mbps | 1.5 Mbps |
| 854×480 | 2.5 Mbps | 4 Mbps |
| 1280×720 | 5 Mbps | 7.5 Mbps |
| 1920×1080 | 8 Mbps | 12 Mbps |
| 2560×1440 | 16 Mbps | 24 Mbps |
| 3840×2160 | 40 Mbps | 60 Mbps |
| 7680×4320 | 120 Mbps | 180 Mbps |
| larger | 480 Mbps | 720 Mbps |

A composition falls in the first row whose pixel count (width × height) it does not exceed, so 1000×1000 counts as 1920×1080. The bitrate is an average: simple scenes use less, busy ones up to twice as much.

### Encoding settings

On a plan with advanced encoding, `encoding` replaces the quality level's bitrate with your own, for delivery specs such as an ad network's or a TV channel's:

```json
{ "versionId": "7b21…", "codec": "h264", "encoding": { "rateControl": "vbr", "bitrateKbps": 8000, "maxBitrateKbps": 12000, "keyframeIntervalSeconds": 2, "h264Profile": "high" } }
```

| Field | Values | Default |
|---|---|---|
| `rateControl` | `quality` (the [quality](#quality) level sets the bitrate), `vbr` (an average bitrate that may rise to `maxBitrateKbps` in busy scenes) or `cbr` (a steady bitrate held close to `bitrateKbps`; very detailed or noisy scenes can go over it, and simple scenes can come out below it, since no filler is added) | `quality` |
| `bitrateKbps` | Required with `vbr` and `cbr`: 300 to 160,000 | — |
| `maxBitrateKbps` | With `vbr` only: at least `bitrateKbps`, at most 160,000 | twice `bitrateKbps` |
| `keyframeIntervalSeconds` | 0.5 to 10: a keyframe at least this often, which seeking and many ad and streaming specs need | the encoder's |
| `h264Profile` | With codec `h264` only: `baseline`, `main` or `high`, for older players that need a lower profile | the encoder's |

The render's `encoding` field shows the settings it was made with. A request without `encoding`, or with `{}`, renders at the quality level.

### Live HLS

An HLS render can be watched while it renders. Once its first segments are ready, `playback` turns `streaming` and `output.hlsUrl` is set, while `status` is still `rendering`. `mp4Url` and `posterUrl` stay `null` until it succeeds. The `EVENT` playlist grows as segments finish, so players start at the beginning and keep loading. When the render succeeds, the playlist gets `#EXT-X-ENDLIST`, and the same URL plays the whole video.

If the render fails or is cancelled, `output` turns `null`, the playlist and segment URLs respond with `404`, and the partial video is deleted. A render that had started streaming is not refunded, unless it failed on Blitframe's side ([pricing](#pricing)).

### Posters

A succeeded MP4 or HLS render has `posterUrl`: a JPEG of the frame halfway through the video, at the composition's size. Use it as a video poster or preview image. It is `null` in the rare case it could not be made, and the video is unaffected. Frame renders have no poster. A project shows the poster of its latest succeeded video render as `thumbnailUrl`.

### Download file names

The MP4 downloads as `{project name}-{version name}.mp4`. A version without a [name](/docs/blitframe/projects#editing-a-project) uses its number, such as `Summer sale-v5.mp4`. A render created with `name` downloads as `{name}.mp4`, so in a batch, give each render its own `name`.

Characters that file systems refuse (`\ / : * ? " < > |` and control characters) become `-`, or a space when a space is already next to them. For example, `Launch: ad` downloads as `Launch ad.mp4`. Names are cut at 180 characters. Renaming the project renames its renders' downloads the next time you fetch them.

### Queue order

Renders start as GPUs free up. While renders wait, each workspace gets a share of render capacity set by its plan: the workspace with the fewest renders running for its share goes next, and on a plan with a priority render queue its renders start a few minutes ahead. No plan waits behind another indefinitely, and within a workspace renders start in the order they were queued.

In a batch, renders without replacements wait for a GPU at once. The versions of renders with replacements are made one after another, usually a few seconds each, before those renders wait for a GPU too.

### Deleted renders in archives

A [download archive](#download-many-videos-as-one-zip) that already holds a render you delete stays downloadable until the archive expires.
