Async Render

Queue a Chromium render, receive a job ID immediately, and poll until the image is ready.

POST/v1/render/async

When to use it

Use async rendering when your application cannot keep an HTTP request open while Chromium loads fonts, external images, JavaScript, or delayed content. For fast HTML and CSS, use /v1/render/fast. For a normal blocking request, use /v1/render.

ℹ️

Async rendering uses the same Chromium renderer and accepts the same request parameters as POST /v1/render.

1. Submit a render

Authenticate with your API key and send either html or a saved template_id.

cURL

curl -X POST https://api.starkrender.com/v1/render/async \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<div style=\"width:1080px;height:1080px;background:#111;color:#fff;display:flex;align-items:center;justify-content:center;font-size:72px\">Async render</div>",
    "width": 1080,
    "height": 1080,
    "format": "png"
  }'

Accepted response

A successful submission returns HTTP 202 Accepted.

JSON · 202

{
  "ok": true,
  "job_id": "79e10d45-04f1-4d46-b86a-6bf1dc03c40e",
  "status": "queued",
  "queue_size": 1
}

2. Poll the job

GET/v1/render/async/{job_id}

Send the same API key and replace {job_id} with the ID returned by the submit request.

cURL

curl https://api.starkrender.com/v1/render/async/79e10d45-04f1-4d46-b86a-6bf1dc03c40e \
  -H "x-api-key: YOUR_API_KEY"

Job states

Status	Description	What to do
`queued`	Waiting for a worker.	Poll again.
`running`	Chromium is rendering the image.	Poll again.
`done`	The image is ready in `result`.	Use `result.url`.
`error`	The render failed. Details are in `error`.	Fix the input or retry.

Completed response

JSON · 200

{
  "id": "79e10d45-04f1-4d46-b86a-6bf1dc03c40e",
  "status": "done",
  "created_at": 1785252000.12,
  "started_at": 1785252000.18,
  "finished_at": 1785252002.44,
  "result": {
    "url": "https://api.starkrender.com/v1/image/2e10...",
    "id": "2e10..."
  },
  "error": null
}

Polling example

JavaScript

const headers = {
  "x-api-key": process.env.STARKRENDER_API_KEY,
  "Content-Type": "application/json"
};

const submitted = await fetch(
  "https://api.starkrender.com/v1/render/async",
  { method: "POST", headers, body: JSON.stringify({ html, width: 1080, height: 1080 }) }
).then(r => r.json());

while (true) {
  await new Promise(resolve => setTimeout(resolve, 1000));
  const job = await fetch(
    `https://api.starkrender.com/v1/render/async/${submitted.job_id}`,
    { headers: { "x-api-key": process.env.STARKRENDER_API_KEY } }
  ).then(r => r.json());

  if (job.status === "done") {
    console.log(job.result.url);
    break;
  }
  if (job.status === "error") throw new Error(job.error);
}

Errors and limits

HTTP	Meaning
`400`	The submit request does not include `html` or `template_id`.
`401`	The API key is missing, invalid, or has reached its plan limit.
`404`	The job ID does not exist or is no longer available.
`429`	The async render queue is full. Retry with exponential backoff.

A completed async render counts as one render, just like /v1/render.
Poll approximately once per second; aggressive polling does not make rendering faster.
Job status is held in memory and may be unavailable after an API restart. If a job returns 404, submit it again.
Store the returned image URL instead of depending on the job status response as permanent storage.