HTML to PDF API

POST /api/v1/html-to-pdf turns an HTML string, an uploaded .html file, or a live URL into a print-ready PDF. Forty-seven rendering options, PDF/A, e-invoice XML and password protection on the same call.

Don't want to build the markup? Design the document in the visual editor and render it with your data — see Templates.

Authenticate with your API key: Authorization: Bearer YOUR_API_KEY. Get a key — your first 300 renders are free, no card. After that, see plans and pricing.

Fonts are installed server-side, so your HTML does not have to ship them: Vietnamese, Chinese, Japanese, Korean, Thai, Arabic, Cyrillic and colour emoji all render. Web fonts your page loads itself (Google Fonts and the like) are fetched and embedded as usual.

Quick start — pick your input

Three ways to send a document. Same options, same output, same price. Copy one and run it.

1 · An HTML string

When your code generates the document per request — an invoice, a report, a ticket.

curl -X POST "https://api.saypdf.com/api/v1/html-to-pdf" \
  -H "Authorization: Bearer $SAYPDF_KEY" \
  -H "Content-Type: application/json" \
  -o invoice.pdf \
  -d '{
        "source": { "html": "<h1>Invoice #123</h1><p>Total: $42.00</p>" },
        "options": { "format": "A4", "margin": "15mm" }
      }'

2 · Upload the HTML file

When the document is a file on disk. No escaping a large template into a JSON string, and no shell quoting to get wrong. Options travel as a JSON string, because multipart has no objects.

curl -X POST "https://api.saypdf.com/api/v1/html-to-pdf" \
  -H "Authorization: Bearer $SAYPDF_KEY" \
  -F "file=@invoice.html" \
  -F 'options={"format":"A4","margin":"15mm"}' \
  -o invoice.pdf

3 · A live URL

Loaded the way a browser would, so the page's own stylesheets, images and fonts resolve.

curl -X POST "https://api.saypdf.com/api/v1/html-to-pdf" \
  -H "Authorization: Bearer $SAYPDF_KEY" \
  -H "Content-Type: application/json" \
  -o page.pdf \
  -d '{ "source": { "url": "https://example.com" } }'

Try it from this page

Press Render PDF below and a real PDF comes back — nothing to fill in, no signup, no key to fetch first. A key is minted for you on the first render, good for 25 renders over 24 hours. A free account gets one that does not expire, with 300.

Plans — subscribe without leaving this page

Your first 300 renders are free. After that, pick the plan that covers your pace. HTML → PDF consumes one render per request; document conversion and OCR use a separate page allowance. The per-render figure is the monthly price divided by the renders it includes — the number to compare against anyone else's.

Already subscribed? Manage your subscription. Prefer to buy in blocks instead of monthly? Top up credits.

Input — exactly one

Stylesheets, images and fonts

An HTML file almost never travels alone. There are three ways to make href="css/style.css" resolve, and all three work:

A .zip here means the document and the folders it references, zipped exactly as they sit on disk — nothing has to be rearranged:

site.zip
  index.html        <- the entry point (or the shallowest .html if there is no index)
  css/style.css     <- href="css/style.css" resolves, because the path is kept
  js/app.js
  img/logo.png

Zipping the folder works too: site/index.html, site/css/style.css … is rebased on site/, so what your operating system produces when you right-click a folder and compress it is already the right shape.

curl -X POST https://api.saypdf.com/api/v1/html-to-pdf \
  -H "Authorization: Bearer $SAYPDF_KEY" \
  -F "file=@site.zip" \
  -F 'options={"format":"A4","margin":"15mm"}' \
  -o out.pdf

The same folder, from a browser's directory picker:

const fd = new FormData();
const paths = [];
for (const f of input.files) {          // <input type="file" webkitdirectory>
  fd.append("files", f);
  paths.push(f.webkitRelativePath);     // "site/css/style.css"
}
fd.append("paths", JSON.stringify(paths));
fd.append("options", JSON.stringify({ format: "A4" }));
await fetch("https://api.saypdf.com/api/v1/html-to-pdf", {
  method: "POST", headers: { Authorization: `Bearer ${key}` }, body: fd,
});

Limits: 200 files and 30 MB of assets per render. A missing asset does not fail the render by default — the page is drawn without it, exactly as a browser would. Set fail_on_resource if you would rather be told.

Output — output = inline · url · base64

Also accepted at the top level: filename (used in Content-Disposition) and clientReference (echoed back for your own correlation).

Rendering options

All optional. The defaults are A4 portrait, 15 mm margins, backgrounds printed, print stylesheet, no header or footer, untagged.

Paper

Ink

Content

Waiting for the page

Loading behaviour

PDF flavour

Finishing

All of it is billed the same: one render uses one HTML/API render allowance, whatever the page count and whatever finishing it asks for.

E-invoices (ZUGFeRD / Factur-X)

Pass your CII XML and the result is a PDF/A-3 with the invoice embedded as factur-x.xml, the correct AFRelationship and the Factur-X XMP extension schema — a file a German or French buyer's system will accept.

{
  "source": { "html": "<h1>Rechnung RE-2026-1001</h1>" },
  "options": {
    "facturx": {
      "xml": "<rsm:CrossIndustryInvoice>…</rsm:CrossIndustryInvoice>",
      "conformance": "EN 16931"
    }
  }
}

Profiles: MINIMUM, BASIC WL, BASIC, EN 16931 (default), EXTENDED, XRECHNUNG. See the e-invoicing API docs for generating the XML itself.

JavaScript

const res = await fetch("https://api.saypdf.com/api/v1/html-to-pdf", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SAYPDF_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source: { html: renderInvoiceHtml(order) },
    options: {
      format: "A4",
      margin: { top: "25mm", bottom: "20mm", left: "15mm", right: "15mm" },
      footer: '<div style="text-align:center"><span class="pageNumber"></span> / <span class="totalPages"></span></div>',
      wait_for_selector: "#chart",
    },
  }),
});
if (!res.ok) throw new Error(await res.text());
console.log("free pages left:", res.headers.get("X-Free-Pages-Remaining"));
const pdf = Buffer.from(await res.arrayBuffer()); // store / email

Python

import requests

r = requests.post(
    "https://api.saypdf.com/api/v1/html-to-pdf",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "source": {"html": html_string},
        "options": {"format": "A4", "margin": "15mm", "pdfa": "PDF/A-3b"},
    },
)
r.raise_for_status()
print("free pages left:", r.headers.get("X-Free-Pages-Remaining"))
open("out.pdf", "wb").write(r.content)

Templates — design once, render with data

Save a document design and render it with a row of data, instead of building the markup on every call. Design it in the visual editor — drag text, images, tables and barcodes onto the page — or write it as HTML. Templates are free; only rendering one is billed, at the same one render as everything else.

Two engines, one endpoint

# save an HTML template with a repeating line-item table
curl -X POST https://api.saypdf.com/api/v1/templates \
  -H "Authorization: Bearer $SAYPDF_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice",
    "engine": "html",
    "body": "<h1>Invoice {{number}}</h1><table>{{#lines}}<tr><td>{{name}}</td><td>{{total}}</td></tr>{{/lines}}</table>",
    "options": { "format": "A4", "margin": "18mm" }
  }'

# render it
curl -X POST https://api.saypdf.com/api/v1/templates/<id>/render \
  -H "Authorization: Bearer $SAYPDF_KEY" -H "Content-Type: application/json" \
  -d '{ "data": { "number": "RE-1001", "lines": [ {"name":"Consulting","total":"1.200,00 €"} ] } }' \
  -o invoice.pdf

options saved with the template are the defaults; anything you send on the render call overrides them for that call only — so one page in landscape does not need a second template. For a pdfme template, sending data as an array of objects renders one document per entry into a single PDF, which is what a run of 200 certificates is.

Managing templates works with an API key or a signed-in session, because both are real: you edit a design in the browser and render it from a server. Rendering needs an API key.

Long documents — paged, async, webhooks

paged: true — real CSS Paged Media

Pagination starts after your readiness conditions, optional delay, fonts and images complete. Conversion then waits for pagination to finish.

Runs the document through Paged.js before printing. What that buys, measured against this API rather than quoted from a spec:

{
  "source": { "html": "<style>@page{@top-center{content:string(ch)}} h2{string-set:ch content()}</style>…" },
  "options": { "paged": true }
}

paged applies to source.html and uploads only — the polyfill has to be injected into the document, which is impossible for a source.url page loaded by the browser. Margins are handled by your @page rule; the engine prints edge to edge so they are not applied twice. Expect a second or two more on a long document.

async: true and webhookUrl

A long render should not hold your connection open — every proxy and HTTP client in the chain is entitled to time out on it, and a render that has already been paid for is then thrown away.

curl -X POST https://api.saypdf.com/api/v1/html-to-pdf \
  -H "Authorization: Bearer $SAYPDF_KEY" -H "Content-Type: application/json" \
  -d '{"source":{"html":"…"},"async":true,"webhookUrl":"https://you.example.com/hook"}'

{ "success": true, "status": "processing", "fileId": "…",
  "statusUrl": "…/api/v1/convert/<id>/status", "resultUrl": "…/api/v1/convert/<id>/result" }

Poll statusUrl, or give a webhookUrl and we POST { fileId, clientReference, success, status, url } when it finishes — including on failure, with error. Billed exactly like a synchronous call. The webhook must be a public http(s) address: private, loopback and cloud-metadata addresses are refused, because a webhook is an address we connect to.

Knowing what is left

Every metered response carries the allowance, so you never have to poll anything or open a dashboard to find out you are close:

They are on refusals too, so a 400 for quota tells you how far over you are — and the body names the plan that covers your current pace, rather than sending you to a pricing table.

Programmatic view of the same numbers: GET /api/v1/account/quota, and GET /api/v1/account/upgrade-advice for the recommendation.

Errors

Other conversions

POST /api/v1/convert handles everything else — Word, Excel, PowerPoint, images and SVG to PDF, PDF to Office formats, OCR. It also still accepts typeConvert: "html_to_pdf" for existing integrations, but new work should use /api/v1/html-to-pdf: it renders synchronously instead of queueing, documents and validates the full option surface above, and takes a URL source directly.

Notes

• Max input size: 60 MB.
• One render consumes one HTML/API render allowance, regardless of page count or finishing steps.
• inline and base64 responses are not stored. url output is stored so the link works, and deleted on the retention schedule in our privacy policy.
• Rate limits and plan quotas are per account — see plans.

What we have actually measured

Every row below was rendered against this API and checked in the resulting PDF — text extracted, image objects counted, page boxes measured — not assumed from a feature list. The ones that failed were fixed; they are listed too, because a list with no failures in it is not a measurement.