API reference / Renders

Create a batch of renders

POST/v1/projects/{projectId}/renders/batch

Queues up to 1,000 renders of one version of the project: versionId, or else the head of a variation (variation, or main when it is left out). Each render has the options of a single render request (format, quality, frames, audio, name, replacements). Every render is checked first, its replacements and uploads included; if any is refused, nothing is queued or charged, and the message starts with renders[i]. Each upload can be named by one render only. The answer names the version every render uses, and leaves out each render's replacements and frame links; get one render for them. The body may be up to 64 MB (413 too_large). Send an Idempotency-Key header (1 to 200 characters, no '/', not starting with 'share:') to make retries safe: for 24 hours the same batch with the same key answers with the same renders, with the header Idempotent-Replayed: true; the same key with a different request is 422 idempotency_key_reused.

Request

curl -s -X POST $BLITFRAME/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/renders/batch \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1ddd7b06-55f6-01e4-a59d-4b1376fdb00f" \
  -d '{
    "versionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
    "renders": [
      {
        "format": "mp4",
        "name": "Spanish",
        "replacements": [{"layer": "/layers/0", "text": "Rebajas de verano"}]
      },
      {"format": "hls", "quality": "medium"}
    ]
  }'
import os, requests

response = requests.post(
    f"{os.environ['BLITFRAME']}/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/renders/batch",
    headers={
        "Authorization": f"Bearer {os.environ['BLITFRAME_API_KEY']}",
        "Idempotency-Key": "1ddd7b06-55f6-01e4-a59d-4b1376fdb00f",
    },
    json={
        "versionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
        "renders": [
            {
                "format": "mp4",
                "name": "Spanish",
                "replacements": [{"layer": "/layers/0", "text": "Rebajas de verano"}],
            },
            {"format": "hls", "quality": "medium"},
        ],
    },
)
print(response.json())
const response = await fetch(`${process.env.BLITFRAME}/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/renders/batch`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "1ddd7b06-55f6-01e4-a59d-4b1376fdb00f",
  },
  body: JSON.stringify({
    versionId: "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
    renders: [
      {
        format: "mp4",
        name: "Spanish",
        replacements: [{ layer: "/layers/0", text: "Rebajas de verano" }],
      },
      { format: "hls", quality: "medium" },
    ],
  }),
});
console.log(await response.json());
<?php
$request = curl_init(getenv("BLITFRAME") . "/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/renders/batch");
curl_setopt_array($request, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BLITFRAME_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: 1ddd7b06-55f6-01e4-a59d-4b1376fdb00f",
    ],
    CURLOPT_POSTFIELDS => '{
      "versionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
      "renders": [
        {
          "format": "mp4",
          "name": "Spanish",
          "replacements": [{"layer": "/layers/0", "text": "Rebajas de verano"}]
        },
        {"format": "hls", "quality": "medium"}
      ]
    }',
]);
$response = curl_exec($request);
echo $response;
require "net/http"

uri = URI(ENV["BLITFRAME"] + '/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/renders/batch')
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer " + ENV["BLITFRAME_API_KEY"]
request["Content-Type"] = "application/json"
request['Idempotency-Key'] = '1ddd7b06-55f6-01e4-a59d-4b1376fdb00f'
request.body = '{
  "versionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
  "renders": [
    {
      "format": "mp4",
      "name": "Spanish",
      "replacements": [{"layer": "/layers/0", "text": "Rebajas de verano"}]
    },
    {"format": "hls", "quality": "medium"}
  ]
}'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }
puts response.body
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{
	  "versionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
	  "renders": [
	    {
	      "format": "mp4",
	      "name": "Spanish",
	      "replacements": [{"layer": "/layers/0", "text": "Rebajas de verano"}]
	    },
	    {"format": "hls", "quality": "medium"}
	  ]
	}`)
	request, err := http.NewRequest("POST", os.Getenv("BLITFRAME")+"/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/renders/batch", body)
	if err != nil {
		panic(err)
	}
	request.Header.Set("Authorization", "Bearer "+os.Getenv("BLITFRAME_API_KEY"))
	request.Header.Set("Content-Type", "application/json")
	request.Header.Set("Idempotency-Key", "1ddd7b06-55f6-01e4-a59d-4b1376fdb00f")
	response, err := http.DefaultClient.Do(request)
	if err != nil {
		panic(err)
	}
	defer response.Body.Close()
	text, _ := io.ReadAll(response.Body)
	fmt.Println(string(text))
}
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post,
    Environment.GetEnvironmentVariable("BLITFRAME") + "/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/renders/batch");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLITFRAME_API_KEY"));
request.Headers.Add("Idempotency-Key", "1ddd7b06-55f6-01e4-a59d-4b1376fdb00f");
request.Content = new StringContent(
    """
    {
      "versionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
      "renders": [
        {
          "format": "mp4",
          "name": "Spanish",
          "replacements": [{"layer": "/layers/0", "text": "Rebajas de verano"}]
        },
        {"format": "hls", "quality": "medium"}
      ]
    }
    """, Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        var request = HttpRequest.newBuilder(URI.create(System.getenv("BLITFRAME") + "/projects/c1edf0fb-045f-4c8a-af93-6d5e6e554334/renders/batch"))
            .header("Authorization", "Bearer " + System.getenv("BLITFRAME_API_KEY"))
            .header("Content-Type", "application/json")
            .header("Idempotency-Key", "1ddd7b06-55f6-01e4-a59d-4b1376fdb00f")
            .method("POST", HttpRequest.BodyPublishers.ofString("""
                {
                  "versionId": "5c3d7a8e-2f41-4b6a-9d10-7e2f5a9c1b34",
                  "renders": [
                    {
                      "format": "mp4",
                      "name": "Spanish",
                      "replacements": [{"layer": "/layers/0", "text": "Rebajas de verano"}]
                    },
                    {"format": "hls", "quality": "medium"}
                  ]
                }
                """))
            .build();
        var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Path parameters

  • projectIdstring (uuid)required

Headers

  • AuthorizationBearer Blitframe API keyrequired

    API key from the developer console.

  • Idempotency-Keystring

    Optional. A unique key you choose for this one request, 1 to 200 characters, such as a new UUID. Send the same key again only to retry this request after a lost answer: the retry answers with what the first one made instead of doing it again. Use a new key for every other request; the key in the samples is only an example.

Body

application/json · required · CreateRenderBatchRequest

  • versionIdstring (uuid) or null
  • rendersarray of RenderBatchItem or null
    RenderBatchItem fields
    • One of mp4 hls frames

    • One of low medium high extraHigh

    • framesFrameRange or null
      FrameRange fields
      • startintegerrequired
      • endintegerrequired
      • One of png jpeg tga

        Default png

    • audioAudioTrack or null
      AudioTrack fields
      • pathstringrequired
      • offsetSecondsnumber

        Default 0

    • namestring or null
    • replacementsarray of Replacement or null
      Replacement fields
      • layerstringrequired
      • textstring or null
      • fontstring or null
      • pathstring or null
      • fileEditFile or null
        EditFile fields
        • pathstringrequired
        • contentstring or null
        • contentBase64string or null
        • uploadIdstring (uuid) or null
        • fromVersionIdstring (uuid) or null
        • fromPathstring or null
      • fitMediaFit or null

        One of contain cover

    • One of h264 hevc av1

    • encodingRenderEncoding or null

      Encoder settings a render asks for; without them its quality level sets a variable bitrate.

      RenderEncoding fields
      • rateControlRateControl

        One of quality vbr cbr

      • bitrateKbpsinteger or null
      • maxBitrateKbpsinteger or null
      • keyframeIntervalSecondsnumber or null
      • h264ProfileH264Profile or null

        One of baseline main high

  • variationstring or null

Try it

POST/v1/projects/{projectId}/renders/batch

Used for the requests you send from this page only. It is not saved.

This sends a real request to your workspace: a render spends render seconds, and a delete is final.

Response

Send the request to see the answer here.

Responses

  • 202 Accepted

application/json · RenderBatchDto

  • versionIdstring (uuid)
  • rendersarray of RenderDto
    RenderDto fields
    • idstring (uuid)
    • projectIdstring (uuid)
    • versionIdstring (uuid) or null
    • sourceVersionIdstring (uuid)
    • One of mp4 hls frames

    • One of low medium high extraHigh

    • framesFrameRange or null
      FrameRange fields
      • startinteger
      • endinteger
      • One of png jpeg tga

    • audioAudioTrack or null
      AudioTrack fields
      • pathstring
      • offsetSecondsnumber
    • One of queued rendering succeeded failed cancelled

    • errorApiError or null
      ApiError fields
      • codestring
      • messagestring
    • chargedSecondsinteger (int64)
    • refundedSecondsinteger (int64)
    • createdAtstring (date-time)
    • startedAtstring (date-time) or null
    • finishedAtstring (date-time) or null
    • outputRenderOutputDto or null
      RenderOutputDto fields
      • mp4Urlstring or null
      • hlsUrlstring or null
      • frameUrlsarray of string or null
      • expiresAtstring (date-time)
      • posterUrlstring or null
    • namestring or null
    • playbackPlaybackState or null

      One of preparing streaming complete

    • replacementsarray of Replacement or null

      The replacements the render was created with. Left out unless one render is read: only the answer to creating a render and GET /v1/renders/{renderId} carry it, and only for a render with replacements.

      Replacement fields
      • layerstring
      • textstring or null
      • fontstring or null
      • pathstring or null
      • fileEditFile or null
        EditFile fields
        • pathstring
        • contentstring or null
        • contentBase64string or null
        • uploadIdstring (uuid) or null
        • fromVersionIdstring (uuid) or null
        • fromPathstring or null
      • fitMediaFit or null

        One of contain cover

    • codecVideoCodec or null

      One of h264 hevc av1

    • encodingRenderEncoding or null

      Encoder settings a render asks for; without them its quality level sets a variable bitrate.

      RenderEncoding fields
      • rateControlRateControl

        One of quality vbr cbr

      • bitrateKbpsinteger or null
      • maxBitrateKbpsinteger or null
      • keyframeIntervalSecondsnumber or null
      • h264ProfileH264Profile or null

        One of baseline main high

Errors

  • 400 Bad Request
  • 401 Unauthorized
  • 402 Payment Required
  • 403 Forbidden
  • 404 Not Found
  • 409 Conflict
  • 413 Payload Too Large
  • 422 Unprocessable Entity
  • 429 Too Many Requests

application/json · ErrorResponse

  • ApiError fields
    • codestring
    • messagestring

Errors lists the error codes and says when to retry.