Format Parameter

The format parameter switches the output between a PNG image (the default) and a PDF document. It works on the HTML/CSS API, the Screenshot API and the template endpoints.

Looking for the overview rather than the reference? See the HTML to PDF API page.

Specifications

Property	Value
Type	string
Required	No
Default	png
Allowed values	png, pdf
API	HTML/CSS, Screenshot and Template APIs

Description

When format is set to pdf:

• The result is a real, vector PDF - text stays selectable and searchable, and fonts (including webfonts) are embedded in the document
• Content is laid out on A4 portrait pages and paginates automatically, so long content flows across as many pages as it needs
• Background colours, gradients and images are included
• The page renders with your normal screen CSS, so the PDF looks like the image output would - @media print rules are not applied
• The response url points to a .pdf file served with the application/pdf content type

Only genuine raster content (<img> elements, canvases) is embedded as pixels; everything else in the PDF is vector.

Examples

HTML to PDF

{
    "html": "<h1>Invoice #1042</h1><p>Due within 30 days.</p>",
    "css": "h1 { color: #4f46e5; }",
    "format": "pdf"
}

Web page to PDF

{
    "url": "https://example.com",
    "format": "pdf"
}

Async PDF with a webhook

{
    "html": "<h1>Monthly report</h1>",
    "format": "pdf",
    "webhook_url": "https://your-domain.com/webhook"
}

Response

{
    "success": true,
    "id": "9d5f9b52-6b32-4a1c-a9c5-1f0b2a9e4c11",
    "expires_at": null,
    "credits_remaining": 499,
    "url": "https://i.html2img.com/image-1784019129398-416501.pdf"
}

A PDF conversion costs the same single credit as an image conversion.

Common values

• png (default) - a PNG image sized by width and height, with optional dpi scaling.
• pdf - an A4 portrait PDF document with selectable text and automatic pagination.

When to use

Use format: "pdf" when the output is a document rather than a picture: invoices, receipts, reports, certificates, tickets, or printable versions of generated content. Anyone opening the file can select and copy the text, search inside it, and print it at full quality. The HTML to PDF API page covers rendering your own markup as a document; the URL to PDF API page covers converting live pages.

Stay with the default PNG for social cards, OG images, thumbnails and anywhere the output is displayed inside another page at fixed pixel dimensions.

Common mistakes

• Expecting width and height to size the PDF. PDF pages are A4 portrait and content reflows to the page width. Design your markup to flow like a document rather than to fixed pixel dimensions, or pass scale_to_fit to scale a fixed-width design onto the page.
• Raising dpi to sharpen the output. PDF output is vector, so it is already sharp at any zoom level. The dpi value is ignored in PDF mode.
• Relying on @media print styles. The PDF is rendered with screen CSS so it matches the image output. Put everything the PDF needs in your normal styles.
• Using selector or fullpage. Neither applies to PDFs - the whole document is captured and paginated automatically.

See also: getting started guide, scale_to_fit, webhook_url, css.