How to Convert HTML to PDF with an API — The Complete Guide

Generating PDFs from HTML is one of the most common developer tasks that's surprisingly annoying to get right. Fonts break, layouts shift, headers/footers don't work, and CSS print styles are a nightmare.

This guide covers every approach: self-hosted tools, cloud APIs, and when to use each one.

Why Is HTML-to-PDF So Hard?

HTML was designed for screens, not paper. Converting it to a fixed-layout format like PDF means dealing with:

• Page breaks — Where does content split between pages?
• Headers and footers — Repeated content across pages
• Font rendering — System fonts vary across OS; servers often lack them
• CSS support — Not all CSS works in PDF generators
• JavaScript — Does the tool execute JS before rendering?

Option 1: Puppeteer (Self-Hosted)

The most popular free option. Puppeteer launches a headless Chrome instance and uses its built-in PDF printer.

const puppeteer = require('puppeteer');

async function htmlToPdf(html) {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.setContent(html, { waitUntil: 'networkidle0' });
  const pdf = await page.pdf({
    format: 'A4',
    printBackground: true,
    margin: { top: '20mm', bottom: '20mm', left: '15mm', right: '15mm' }
  });
  await browser.close();
  return pdf;
}

Pros: Free, full CSS/JS support, excellent rendering quality.

Cons: Memory-hungry (~80-150MB per instance), slow cold starts, needs Chrome installed on server, zombie processes, concurrency is painful.

When to use: Low volume (< 100 PDFs/day) and you have server ops capacity.

Option 2: wkhtmltopdf

An older tool that uses a WebKit engine. Still widely used but showing its age.

wkhtmltopdf --enable-local-file-access input.html output.pdf

Pros: Fast, low memory, CLI-friendly.

Cons: Outdated WebKit (no modern CSS), no JS execution, deprecated by maintainers.

When to use: Simple documents with basic formatting. Not recommended for new projects.

Option 3: Cloud API (PDFMagic)

Let someone else deal with headless browsers. Send HTML, get a PDF back.

# Convert a URL to PDF
curl -X POST "https://pdf.grabshot.dev/api/pdf" \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "format": "A4"}' \
  --output document.pdf

# Convert raw HTML to PDF
curl -X POST "https://pdf.grabshot.dev/api/pdf" \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"html": "<h1>Invoice #1234</h1><p>Total: $99</p>", "format": "A4"}' \
  --output invoice.pdf

Pros: No infrastructure to manage, handles concurrency, consistent rendering, fast.

Cons: Costs money at scale, your HTML leaves your server.

When to use: Any volume where you value your time over server costs. Especially good for invoices, reports, and documents where reliability matters.

Common Use Cases

Invoices and Receipts

The #1 use case. Design your invoice in HTML/CSS (much easier than a PDF library), then convert to PDF. Use a template engine like Handlebars or EJS to inject data.

Reports and Dashboards

Render charts with Chart.js or D3, then capture the full page as PDF. Cloud APIs handle the JS execution automatically.

Contracts and Legal Documents

Consistent rendering is critical here. Self-hosted Puppeteer with pinned Chrome versions, or a cloud API, are the safest choices.

E-commerce (Shipping Labels, Packing Slips)

High volume, needs to be fast. Cloud API or a well-tuned Puppeteer pool with worker processes.

Performance Tips

1. Reuse browser instances — Don't launch/close Chrome for every PDF. Keep a pool.
2. Inline your CSS — External stylesheets add network requests and slow rendering.
3. Avoid huge images — Resize before embedding. A 5MB hero image in a PDF is wasteful.
4. Use waitUntil: 'networkidle0' — Ensures all resources loaded before capture.
5. Set explicit page size — Don't rely on defaults. Specify A4, Letter, or custom dimensions.

Which Approach Should You Choose?

Just getting started? Use PDFMagic's free tier. No infrastructure, no headaches.

Need full control? Self-host Puppeteer, but budget time for ops work.

High volume production? Cloud API is almost always cheaper than the engineering time to build and maintain your own PDF pipeline.