Endpoint reference

POST /api/html-to-pdf

Turn an HTML string into a PDF. A headless browser lays it out, so CSS, images and web fonts come out as they do in a browser print. Returns application/pdf.

What it does not do. It takes HTML text only: there is no URL input, and it never opens a page you point it at. JavaScript is switched off, so scripts do not run and a page that builds itself with JavaScript renders empty. External resources load over https from public hosts only (an http:// URL is upgraded to https by the browser); file:, private or internal addresses and redirects to them are blocked. The PDF is untagged (no accessibility tags or outline), and it makes no PDF/A and no form fields. Frames, iframes, objects, embeds, audio and video are not rendered, and AVIF images are not accepted.

Request

Method: POST. URL: https://pdfops.dev/api/html-to-pdf. Body: application/json, or multipart/form-data where html may be a text field or a file. Up to 4.5 MB per request; html itself is capped lower (below). In JSON, numbers and booleans must be JSON numbers and booleans, not strings. In multipart they are sent as text (true, 0.8, and margin as a number or as JSON).

FieldTypeRequiredDescription
htmlStringYesThe document, a full page or a fragment, up to 1 MB of UTF-8. Must not be blank.
page_sizeStringNoletter (default, 612 x 792 pt) or a4 (595 x 842 pt). Every CSS @page rule is removed; this field decides.
landscapeBooleanNoLandscape orientation. Default false.
marginNumber or objectNoPage margin in points, 0 to 144. A number applies to all four sides; an object takes top, right, bottom, left and leaves the sides you omit at the default. Default 36 (0.5 inch) on every side.
print_backgroundBooleanNoPrint background colors and images. Default true.
scaleNumberNoScale of the page content, 0.1 to 2. Default 1.

The optional X-API-Key header works as on /api/merge: no header is anonymous, 100 requests per IP per month; a valid key uses your tier's quota; an invalid or revoked key returns 401 invalid_api_key. A successful (2xx) call counts 5 requests, because rendering costs more than a plain PDF operation. So 100 anonymous requests are 20 renders and a free key's 250 are 50. Once your request reaches the renderer, every outcome is charged. A render that ran, successful or not, counts 5 requests. A refusal the renderer makes before it starts a browser, and only when the analysis took under 250 milliseconds of CPU (html_too_large, html_too_complex for a structure cap, image_too_large for an inline image), counts 1 request. A document that takes long to analyse counts 5. Counting nothing is reserved for a request the API itself rejects before calling the renderer (invalid JSON, a missing html, a bad parameter, html over its size) and a 503 where the renderer was busy, rejected the call, lost its own browser or never answered. A call that would take you past your limit returns 429 rate_limited instead of running. Check consumption with GET /api/usage.

Response

On success: 200 OK, Content-Type: application/pdf, the PDF as the body, plus two headers: x-pdfops-pages (pages in the PDF) and x-pdfops-blocked-requests (external requests our network policy refused or that failed, plus elements removed before rendering such as frames, scripts and preload or prefetch hints; a request the browser refuses on its own, such as a file: URL, is not counted). The page carries no PDFops footer. Nothing is stored: the document is rendered for the response and not kept.

On any failure: 4xx or 5xx, Content-Type: application/json, body is { "error": "<code>", "details": "<explanation>" }.

Images, fonts and external resources

Limits

LimitValueOver the limit
Request body4.5 MB413 request_too_large
html1 MB of UTF-8html_too_large
Output pages50too_many_pages
Output size16,000,000 bytesoutput_too_large
Document structure60,000 elements, 30,000 table cells, nesting 128 deep, 200,000 bytes of <style>, 600,000 bytes of style attributeshtml_too_complex
Image size16 megapixels each, 96 in total, 300 distinct data: URLs, 20 frames, 200,000 bytes of SVGimage_too_large
Image typePNG, JPEG, GIF, WebP, simple SVGunsupported_image
Browser memoryabout 1.2 GBrender_too_heavy
External requests50 per documenttoo_many_resources
External bytes40 MB in total, 8 MB per file, 500,000 bytes of stylesheetsresources_too_large
Render time15 seconds504 render_timeout
Quota5 requests once the renderer is reached; 1 for a refusal decided before a browser starts; nothing for your own validation errors, a busy or unreachable renderer, or a browser that died on its own (see above)429 rate_limited

CSS nesting (with or without &: .card { .title { } }, > .x { }, a:hover { }, several levels), @property and @scope are supported. Ignored without an error (the PDF is still made with a 200): a nested rule whose selector starts with -- (browsers read it as a custom property, not a rule), a nested at-rule other than @media, @supports, @container and @scope (so a nested @layer block is removed), and rules nested more than three levels inside a top-level rule (the rules past that depth, and the declarations after them in the same block, are removed). Stylesheets are decoded with the charset of their Content-Type (UTF-8 by default).

The 15 seconds include starting the browser. The first call after a quiet period can take a few seconds longer than later ones; a typical one-page document renders in well under a second once warm. Typical causes of render_timeout are a slow external resource or very heavy styling: inline your images and remove what you do not need.

Error codes

Error codeStatusTrigger
invalid_json400Request body isn't parseable JSON.
invalid_multipart400The multipart body could not be parsed.
invalid_body400The JSON is valid but is not an object.
missing_html400html is absent or blank.
invalid_html400html is not a string.
html_too_large400html is over 1 MB of UTF-8, or over 4.4 MB once JSON-escaped (control characters and quotes grow when encoded). Counts nothing: the API refuses it before the renderer is called.
invalid_page_size400page_size is not a4 or letter.
invalid_parameter400landscape or print_background is not a boolean, scale is not a number from 0.1 to 2, or margin is not a number from 0 to 144 or an object of such numbers.
too_many_pages400The document is longer than 50 pages. Counts 5 requests.
output_too_large400The PDF would be over 16,000,000 bytes. Counts 5 requests. A table of ten columns fits about 1,000 rows.
html_too_complex400More than 60,000 elements, 30,000 table cells, 200,000 bytes of <style>, 600,000 bytes of style attributes, or nesting over 128 levels, or any stylesheet (inline, style attribute, data: or fetched) with more than 32 unterminated strings, more than 20,000 CSS parse errors or nesting over 100 levels (a fetched resource is refused after the browser started, so that one counts 5 requests): counts 1 request when decided in under 250 milliseconds. A refusal after more than 250 milliseconds of analysis, or an analysis that took over 1 second (documents that take long to analyse): counts 5 requests.
image_too_large400An image is over 16 megapixels, the images total over 96 megapixels, a GIF or WebP has more than 20 frames, an SVG is over its size caps, or there are more than 300 distinct data: URLs. The message names the image. Counts 1 request when found in an inline data: image before rendering, 5 requests when found later in a fetched file.
unsupported_image400An image is of a type that is not accepted (AVIF, BMP, ICO, TIFF, animated PNG), is malformed, is not in the strict canonical form, or is an SVG that is not well-formed, declares an entity, has no usable size or has nothing drawable left. The message names the image and the reason. Counts 1 request for an inline data: image, 5 requests for a fetched one.
render_too_heavy400The browser needed more than about 1.2 GB of memory and was stopped. Counts 5 requests.
too_many_resources400The page asks for more than 50 external resources. Counts 5 requests.
resources_too_large400The external resources total more than 40 MB, or one is over 8 MB, or the stylesheets total more than 500,000 bytes. Counts 5 requests.
request_too_large413The whole request body is over 4.5 MB.
invalid_api_key401An X-API-Key header was sent but the key is unknown or revoked. Get a fresh key at /pricing.
rate_limited429The per-IP limit (anonymous) or your key's tier quota would be exceeded by this call's 5 requests. Retry-After gives seconds until next calendar month.
render_failed500The renderer failed on this document (including a browser that died again after receiving the document a second time). Counts 5 requests.
renderer_unconfigured503HTML to PDF is not enabled on this deployment.
renderer_unavailable503The renderer did not answer, or its browser died on its own and a retry did not get through. Counts nothing. Retry shortly.
renderer_busy503The renderer is at capacity. Retry after the Retry-After seconds.
render_timeout504Rendering took longer than 15 seconds. Counts 5 requests.

Example

A small styled invoice, A4, with a footer line:

curl -X POST https://pdfops.dev/api/html-to-pdf \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pdfops_live_..." \
  -d '{"html": "<!doctype html><style>body{font-family:Arial,sans-serif}h1{color:green}table{width:100%;border-collapse:collapse}td,th{border-bottom:1px solid gray;padding:6px;text-align:left}</style><h1>Invoice 1042</h1><table><tr><th>Item</th><th>Qty</th></tr><tr><td>Widget</td><td>2</td></tr></table><p>Thank you.</p>", "page_size": "a4"}' \
  -o invoice.pdf   # optional key raises your quota to your tier

An HTML file, landscape, with a 20 point margin, as multipart:

curl -X POST https://pdfops.dev/api/html-to-pdf \
  -F "html=@report.html;type=text/html" \
  -F "landscape=true" \
  -F "margin=20" \
  -o report.pdf

Keyless calls work: 100 requests per IP per month with no key, which is 20 renders (or, at 1 request each, 96 refusals: a call needs 5 requests free to start).

Using this for real? A free API key raises the keyless 100 calls per IP to 250 requests a month, with no card.

Get a free API key

Code examples

Have an API key? Add an X-API-Key header to any request. It is optional, and it raises your quota from 100/IP/month to your tier's.

JavaScript (Node.js 22+), built-in fetch
import { writeFile } from 'node:fs/promises';

const headers = { 'Content-Type': 'application/json' };
if (process.env.PDFOPS_API_KEY) headers['X-API-Key'] = process.env.PDFOPS_API_KEY; // optional

const res = await fetch('https://pdfops.dev/api/html-to-pdf', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    html: '<h1>Hello</h1><p>Rendered by a browser.</p>',
    page_size: 'a4',
    margin: 48,
  }),
});
if (!res.ok) {
  const err = await res.json();
  throw new Error(`PDFops html-to-pdf failed: ${err.error}: ${err.details}`);
}
await writeFile('hello.pdf', Buffer.from(await res.arrayBuffer()));
Python, requests
import os, requests

headers = {}
if os.environ.get("PDFOPS_API_KEY"):
    headers["X-API-Key"] = os.environ["PDFOPS_API_KEY"]  # optional

res = requests.post(
    "https://pdfops.dev/api/html-to-pdf",
    headers=headers,
    json={
        "html": "<h1>Hello</h1><p>Rendered by a browser.</p>",
        "page_size": "a4",
        "margin": 48,
    },
)
res.raise_for_status()
with open("hello.pdf", "wb") as f:
    f.write(res.content)

From an AI agent (MCP)

The hosted MCP server at https://pdfops.dev/api/mcp exposes this as the pdf_html_to_pdf tool. It takes the same fields (margin as a single number) and returns the PDF inline as an application/pdf resource. Each call costs 5 requests of quota there too. See PDFops for AI agents.

Behavioral notes

FAQ

How do I convert HTML to PDF with an API?

POST a JSON body with an html field to https://pdfops.dev/api/html-to-pdf. The response is the PDF. Set page_size, landscape, margin, print_background and scale to change the page.

Can I send a URL instead of HTML?

No. The endpoint takes HTML text only. It never opens a page you point it at. Fetch the page yourself and send its HTML, with images inlined as data URIs or served over https.

Does it run JavaScript?

No. Scripts are switched off, so a page that builds itself with JavaScript renders empty or incomplete. Send HTML that is already complete.

Which external resources load?

Images, stylesheets and fonts over https from public hosts, up to 50 requests and 40 MB in total, and data: images, fonts and stylesheets. Everything else is blocked and skipped: http, file, addresses on private or internal networks, and redirects to them. The PDF is still made, and the x-pdfops-blocked-requests header says how many were skipped.

How much quota does a call use?

A render counts 5 requests, because rendering costs more than a plain PDF operation. Once the renderer is reached every outcome counts, failures included: 5 requests, or 1 for a cheap refusal before a browser starts. Only the API's own validation errors (including html_too_large), a busy, rejecting or unreachable renderer, and a browser that died on its own count nothing.

Related: Markdown, text or CSV to PDF · Generate an invoice PDF · Stamp text on a PDF.

Get a free API key. Keyless calls get 100 requests per IP per month; a free key raises that to 250, with no card. Enter your email and the key arrives in your inbox.

Get a free API key