Export & Import

Cloud Render API

Render PNG, JPEG, PDF, SVG, HTML, PPTX, GIF, and MP4 files from Polotno JSON in the cloud

What is Cloud Render API?

Using Polotno SDK, you can generate images directly on the client. But sometimes you need to generate images on the backend. For example, if you want to generate 1,000 images from one template, each with its own data, or if you want to simply offload rendering work from the client.

Polotno Cloud Render API is a managed rendering service that generates PNG, JPEG, PDF, SVG, HTML, PPTX, GIF, and MP4 files without any backend infrastructure. You can use it to generate exports on the fly or to generate them in bulk for automated design workflows.

Cloud Render

Pricing

Trial API keys can create up to 1,000 render requests per day per key. The daily limit resets at midnight UTC; requests over the limit return 429.

For subscribers, Cloud Render API is billed separately at the usage prices: $4 per 10,000 images and $0.03 per video minute.

Before you start

(!) Important: all finished jobs will expire in 1 week. Such jobs will be deleted from the database and all render artifacts (images, PDF, videos, etc) are removed from file storage. Make sure to download the export result. If you need a persistent file store, please contact us.

What does it look like?

1. Create render job

Send a POST request to schedule a rendering job.

const req = await fetch('https://api.polotno.com/api/renders?KEY=YOUR_API_KEY', {
  method: 'POST',
  headers: {
    // it is important to set a json content type
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    // polotno json from store.toJSON()
    design: json,
    // here you can pass other render options
    pixelRatio: 1,
    // see below for full details of options
  }),
});

const job = await req.json();

console.log(job);

It will return a JSON like this:

{
  "id": "fp1f2rtva",
  "status": "scheduled",
  "output": null,
  "error": "",
  "created_at": "2024-05-15T01:41:55.913628+00:00",
  "completed_at": null,
  "started_at": null,
  "updated_at": null,
  "progress": 0,
  "logs": ""
}

Check render job status

// replace jobId with real id of the job
const req = await fetch(`https://api.polotno.com/api/renders/jobId?KEY=YOUR_API_KEY`);
const job = await req.json();

console.log(job);

if (job.status === 'done') {
  console.log(job.output); // link to file, valid only for 7 days after job complete
}

The response also includes the inputs the job was created with: options (render options) and design (a link to the design JSON): useful for debugging a specific render.

Options

  • design: json (required): data from Polotno export store.toJSON(). Without variables, the job draws the design's stored template variable values, as the editor does.
  • variables: object: one record to fill the design's template variables with, such as { "first_name": "Ada", "user": { "city": "London" } }. A dotted name reads nested data. The job fills the design the way resolveVariables does, see Fill a template with data.
  • strict: boolean: fail the job with VARIABLES_INVALID on an error-severity issue: a missing required value or a value of the wrong type. The job's error lists the issues (default: false).
  • format: string: file format of generated result. One of: png (default), jpeg, pdf, svg, html, pptx, gif, mp4. SVG exports the first page by default; HTML includes all pages. A pptx keeps text and simple shapes editable and does not embed fonts, see PPTX Export. Lottie elements render in mp4 and gif output.
  • webhook: string: URL to receive HTTP POST notifications with the full job payload.
  • pixelRatio: number: quality modifier. 0.5 reduces width/height by 2; values > 1 increase quality (and size).
  • ignoreBackground: boolean: remove page background on export (default: false).
  • dpiMetadata: string: control DPI metadata embedding for images. One of: auto (default), always, never.
  • includeBleed: boolean: render bleed areas (default: false).
  • skipFontError: boolean: continue if font loading fails (default: false).
  • skipImageError: boolean: continue if image loading fails (default: false).
  • textOverflow: string: overwrite text overflow logic. Default: change-font-size. Other values: resize, ellipsis.
  • vector: boolean: make pdf in vector format with selectable text (default: false).
  • pdfx: string: with vector: true, emit print-ready PDF/X. One of: x-4 (preferred), x-1a (legacy, flattens transparent pages). The embedded ICC printing condition comes from color.profile.
  • color: object: control color space and profile. space: RGB (default) or CMYK. profile: FOGRA39 (default for CMYK) or USWebCoatedSWOP. SVG and HTML output do not support CMYK.
{
  "color": {
    "space": "CMYK",
    "profile": "FOGRA39"
  }
}

Fill a template with data

Send a template with template variables and one record per job. A batch of a thousand copies is a thousand jobs.

const req = await fetch('https://api.polotno.com/api/renders?KEY=YOUR_API_KEY', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    design: template,
    variables: { first_name: 'Ada', user: { city: 'London' } },
    strict: true,
    format: 'pdf',
  }),
});

Each variable takes the record's value, then its default. Without either, a text keeps the literal {{name}} token and a binding keeps the element's own value, so a broken copy looks broken. With strict: true, an error fails the job at once with VARIABLES_INVALID, and the job's error lists the issues, such as VARIABLES_INVALID: missing-required (first_name). Unknown keys: firstname. Without strict, the job renders and reports no issues; to see a record's warnings, run resolveVariables on it before you send it. See Missing values, issues and strict mode.

See a list of created jobs

List render jobs created with your API key. Supports filtering, ordering, and column selection, so you can use it for debugging and analytics: error monitoring, failure analysis, latency tracking.

const req = await fetch('https://api.polotno.com/api/renders/list?KEY=YOUR_API_KEY&page=1&per_page=100');
const data = await req.json();

console.log(data.renders); // array of jobs
console.log(data.total_count); // total number of jobs matching the filters

It will return a JSON like this:

{
  "renders": [
    {
      "id": "fp1f2rtva",
      "status": "done",
      "output": "https://.../export.png",
      "error": null,
      "created_at": "2026-07-15T01:41:55.913628+00:00",
      "completed_at": "2026-07-15T01:42:01.100000+00:00",
      "started_at": "2026-07-15T01:41:56.200000+00:00",
      "updated_at": "2026-07-15T01:42:01.100000+00:00",
      "progress": 100,
      "logs": "",
      "webhook": null,
      "options": { "format": "png", "pixelRatio": 1 },
      "design": "https://.../cloud-renders/2026/07/15/fp1f2rtva.json"
    }
  ],
  "page": 1,
  "per_page": 100,
  "total_count": 1234,
  "total_pages": 13
}

Every job includes the inputs it was created with: options (the render options you passed) and design (a link to the design JSON), which makes it easy to reproduce and debug a specific render.

Query parameters

  • page: number: page number, starting from 1 (default: 1).
  • per_page: number: jobs per page, up to 1000 (default: 100).
  • status: string: return only jobs with these statuses. Comma-separated list of: scheduled, progress, done, error. Example: status=error or status=scheduled,progress.
  • created_after: string: ISO 8601 date. Return only jobs created strictly after this time.
  • created_before: string: ISO 8601 date. Return only jobs created before this time.
  • order: string: sort by creation time: desc (newest first, default) or asc.
  • fields: string: comma-separated list of fields to return, for lighter responses. Any of: id, status, output, error, created_at, completed_at, started_at, updated_at, progress, logs, webhook, options, design. By default all fields are returned.

Invalid parameters return a 400 response with an explanation.

Common use cases

Count and inspect failed renders for the last day:

const since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
const req = await fetch(
  `https://api.polotno.com/api/renders/list?KEY=YOUR_API_KEY&status=error&created_after=${since}&fields=id,error,created_at`
);
const { renders, total_count } = await req.json();
console.log(`${total_count} failed renders in the last 24h`);

Fetch lightweight data for latency analysis (compute durations as completed_at - created_at):

const req = await fetch(
  'https://api.polotno.com/api/renders/list?KEY=YOUR_API_KEY&status=done&fields=created_at,started_at,completed_at&per_page=1000'
);

Iterate through a large history with created_after and order=asc to avoid the offset pagination limit. Pass the last job's created_at value unchanged as the next cursor; the filter is exclusive.

let cursor = '2026-11-10T00:00:00Z';

while (true) {
  const req = await fetch(
    `https://api.polotno.com/api/renders/list?KEY=YOUR_API_KEY&order=asc&created_after=${encodeURIComponent(cursor)}&per_page=1000`
  );
  if (!req.ok) {
    throw new Error(`Render history request failed: ${req.status}`);
  }
  const { renders } = await req.json();
  if (!renders.length) break;

  // Process this batch of renders.
  console.log(renders);
  cursor = renders[renders.length - 1].created_at;
}

If a batch ends partway through jobs with identical created_at timestamps, advancing the cursor skips the remaining jobs at that timestamp. The API has no unique tie-breaker cursor, so this loop does not guarantee an exhaustive export. Finished jobs still expire after one week.

Limits

  • The list API is limited to 1000 requests per day per API key. When exceeded, it returns 429.
  • Offset pagination is capped: page * per_page must not exceed 100 000. For larger histories, use the created_after loop above, subject to its timestamp caveat.

Synchronous request

Use Prefer: 'wait' for quick renders (e.g., image). The request may still return before completion for long renders (e.g., video).

const req = await fetch('https://api.polotno.com/api/renders?KEY=YOUR_API_KEY', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Prefer: 'wait'
  },
  body: JSON.stringify({
    design: json,
    pixelRatio: 1,
  }),
});

const job = await req.json();

if (job.status === 'error' || job.status === 'done') {
  // handle result
} else {
  // job may still be running; poll status
}

Product overview and pricing for this API: Cloud Render API. For the design side of it, see PDF generation: producing documents from a template and a record.

Try the conversions client-side before you wire up a render job:

Live demo

On this page