Cloud Render API

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 a 1,000 images with different text on it or if you want to simply offload rendering work from the client.

Polotno Cloud Render API allows you to generate images on the cloud without any backend infrastructure. You can use it to generate images on the fly or to generate images in bulk.

Pricing

Cloud Render API is available only for subscribers of Business Plan. For more information, please take a look into pricing. If you have any questions, write as.

What does it look like?

1. Create render 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 bellow for full details of options
  }),
});

const job = await req.json();

console.log(job);

It will return a JSON in format like this:

{
    "id": "pDX17M1D_5DG",
    "status": "scheduled", // can be "scheduled", "progress", "done" or "error"
    "output": null, // when job if finished it will give a link to a file that is valid for 7 days.
    "error": "", // error logs
    "created_at": "2024-05-15T01:41:55.913628+00:00",
    "completed_at": null,
    "started_at": null,
    "updated_at": null,
    "progress": 0, // progress from 0 to 100, available for videos only
    "logs": ""
}

(2) 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
}

Options

design : json, required - data from polotno export store.toJSON(). Remember that you can generate such JSON on the fly from your backend (e.g. replace text on some elements dynamically).

format : string - file format of generated result. Possible values are: png (default), jpeg, pdf, gif and mp4

pixelRatio : number - quality modifier of export. 0.5 value will reduce both width and height by 2. Values larger than 1 will increase quality (and file size).

ignoreBackground : boolean - should we remove page background on export? Default is false

htmlTextRenderEnabled : boolean - enable Rich Text Feature to render HTML strings in text elements. Default is false

textVerticalResizeEnabled : boolean - enable Vertically Resized Text. The default is false.

skipFontError : boolean - continue render process is a font loading is failed. The default is false.

textOverflow : boolean - overwrite overflow logic of text elements. The default is change-font-size

(3) See a list of created jobs

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

console.log(job.renders);

Legacy API Documentation (Ongoing Support)

const req = await fetch('https://api.polotno.com/api/render?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,
    // optional output format for export
    outputFormat: 'dataURL',
    // optional export options for store.toDataURL() method
    exportOptions: {},
  }),
});

const { url } = await req.json();

document.getElementById('image').src = url;

​

When you send request to the API, you need to pass JSON into request's body.

{
  "design": {},
  "outputFormat": "dataURL",
  "exportOptions": {}
}

design​

design - JSON data from polotno export store.toJSON(). Remember that you can generate such JSON on the fly from your backend (e.g. replace text on some elements dynamically).

outputFormat​

outputFormat - defines response format. Possible values are: dataURL (default), url and file.

If you use dataURL or url, API will return json { url: '...' } where url is the generated image url.

file format will return file buffer. You can save it directly on the backend.

⚠️ Important
Cloud API has 5mb limit for its payload!. So it will be not able to return large data in dataURL or file format. You can use url format instead.
Images generated using url format expire in 24 hours. After that time, access to the files is not guaranteed.
You will have to set up the infrastructure for storing files to guarantee the access.

format​

File format of generated result. Possible values are: png (default), jpeg, pdf.

exportOptions​

Options that will be passed into polotno-node export function.

{
  "design": {},
  "exportOptions": {
    // you can pass options that you pass into `store.toDataURL()`
    "pixelRatio": 1,
    "ignoreBackground": false
    "includeBleed": false,
    "htmlTextRenderEnabled": false,
    "textVerticalResizeEnabled": false,
    "skipFontError": true, // do no throw error if font is missing
    "textOverflow": "change-font-size"
  }
}