Skip to Content
DocumentationDeveloper guideBatch Renders API

Batch Renders API

This section covers everything you need to know about API based batch rendering in Plainly. Batches are helpful when you want to create multiple renders for a single project.

Overview

Batch rendering lets you create many renders with a single request. It helps to conserve rate limits, reduces the number of network calls and keeps related renders grouped together.

A batch requires a project and one or more templates. When multiple templates are defined, then each batch data entry is rendered for each given template. This means if you supply two templates and 10 batch data entries, the API will create 20 individual renders. If no template is specified, the project’s default template is used.

As shown in the diagram below, every entry in the batch still results in an individual render object, so webhooks, integrations and any follow-up operations such as cancel or delete continue to apply per render.

Each render in the batch is automatically assigned with the following attributes:

  • batchRenderId - A unique identifier of the batch.
  • batchRenderSequence - The sequence number of the render within the batch.
  • batchRenderGeneratedId - Internal identifier which is always true.

Creating a batch

Send a POST request to /api/v2/batch with shared render options and an array of batchData entries. Each entry defines the following properties and merges the batch-level settings with its own parameters and optional overrides.

NameTypeDefault
parametersRecord<string, any>

The parameters to use for the render.

attributesRecord<string, any>

Custom attributes defined by the user.

integrationsPassthroughstring

Optional integration passthrough data to include when calling integrations for this entry. If not specified, the shared integration settings will be used.

webhookPassthroughstring

Optional webhook passthrough data to include in the webhook payload for this entry. Webhook URL must be defined in shared settings for this to have effect. If not specified, the shared webhook settings will be used.

attachmentFileNamestring

Optional file name without extension for video(s) created by this entry. If not specified, the shared output format settings will be used.

Batch creation is synchronous

The endpoint responds only after all renders are successfully created, so the call may take noticeable time for larger batches. Ensure to increase your HTTP client timeout settings accordingly.

All or nothing

In case of receiving an error response from the API, no renders from the batch will be created.

batch-render.sh
curl -X POST \
  -H "Content-Type: application/json" \
  -u "$PLAINLY_API_KEY:" \
  -d '{
        "projectId": "media-abstract@v1",
        "templateIds": ["square"],
        "reference": "my-internal-ref",
        "webhook": { "url": "https://example.com/callback" },
        "batchData": [
          {
            "parameters": {
              "image": "https://picsum.photos/1920/1920",
              "newsCta": "Book a demo",
              "newsHeading": "Alice",
              "newsSubheading": "Create personalized videos on autopilot",
              "newsLogo": "https://storage.googleapis.com/plainly-static-data/plainly-logo-black.png"
            },
            "webhookPassthrough": "alice-1"
          },
          {
            "parameters": {
              "image": "https://picsum.photos/1920/1920",
              "newsCta": "Start trial",
              "newsHeading": "Bob",
              "newsSubheading": "Try Plainly free for 14 days",
              "newsLogo": "https://storage.googleapis.com/plainly-static-data/plainly-logo-black.png"
            },
            "webhookPassthrough": "bob-2"
          }
        ]
      }' \
  https://api.plainlyvideos.com/api/v2/batch

The returned JSON response will contain the ID of the new batch and all the other properties of the Batch Render object. You can always use this ID to execute a GET request to /api/v2/batch/{batchId} to obtain information about the batch, or a GET request to /api/v2/batch/{batchId}/renders to list all renders created within the batch.

Create batch example JSON response

{
	"id": "ba5b10be-b950-499b-b141-2b9a645c074b",
	"createdDate": "2025-08-29T11:54:24.915Z",
	"projectId": "media-abstract@v1",
	"reference": "my-internal-ref",
	"totalRenders": 2,
	"publicDesign": true
}

Check the Batch Renders API reference  for a complete operation reference.

The API creates one render for each entry in batchData. You can track and manage those renders individually using the standard Render endpoints.

Example code snippets (Node.js)

These snippets illustrate the basic pattern of sending JSON and handling the result. In production you would add error checking, retries and other best practices.

Triggering a batch

import axios from "axios";
 
async function triggerBatch(
	projectId: string,
	templateIds: string[],
	batchData: Array<Record<string, unknown>>,
	additionalConfig?: object,
) {
	const response = await axios.post(
		"https://api.plainlyvideos.com/api/v2/batch",
		{
			projectId,
			templateIds,
			batchData,
			...(additionalConfig || {}),
		},
		{
			auth: {
				username: process.env.PLAINLY_API_KEY!,
				password: "",
			},
			headers: {
				"Content-Type": "application/json",
			},
		},
	);
 
	return response.data;
}

Additional operations

You can also perform the following operations related to batch renders using the API:

Best practices

Same best practices apply to batch renders as to single renders. In addition, consider the following:

  • Control batch size: Keep an eye on the number of renders in a batch. Split into smaller batches if you notice performance issues.
  • Increase HTTP timeouts: Batch creation API call can take a long time, consider increasing the HTTP timeout settings to avoid premature termination.
Renders APIProjects API