HTML To PDF Guide - IyzPdf Client API

POST /convert/html-to-pdf supports three practical workflows:

Send inline HTML as JSON
Upload an HTML file as multipart form data
Render a public URL and capture the result as PDF

When To Use Each Mode

Mode	Best for	Content type
Inline HTML	Server-rendered templates, receipts, invoices, reports	`application/json`
HTML file upload	Existing `.html` assets on disk	`multipart/form-data`
URL mode	Public pages you want to render remotely	`application/json`

JSON Contract

{
  "html": "<!doctype html><html><body><h1>Report</h1></body></html>",
  "url": null,
  "options": {
    "format": "A4",
    "landscape": false,
    "marginTop": "1cm",
    "marginBottom": "1cm",
    "marginLeft": "1cm",
    "marginRight": "1cm",
    "printBackground": true,
    "scale": 1,
    "waitForSelector": ".ready",
    "waitTimeout": 10000
  }
}

Use either html or url, never both in the same request.

Important Limits

Authenticated HTML payloads and HTML uploads are limited to 10 MB
URL mode only accepts public http and https addresses
Private or internal URLs are blocked
waitTimeout cannot exceed 30000 ms
Credit cost is 1 for inline HTML or file upload, 2 for URL mode

Common PDF Options

Field	Meaning
`format`	Paper size such as `A4` or `Letter`
`landscape`	Horizontal page layout
`printBackground`	Include CSS backgrounds and colors
`scale`	Page scale multiplier
`waitForSelector`	Wait until a selector exists before rendering
`waitTimeout`	Maximum wait time in milliseconds

Multipart Upload Shape

When uploading an HTML file, send:

file: the HTML file
options: optional JSON string with the same PdfOptions object

Example:

curl --request POST \
  --url https://api.iyzpdf.com/v1/convert/html-to-pdf \
  --header "X-API-Key: $IYZPDF_API_KEY" \
  --form "file=@invoice.html" \
  --form 'options={"format":"A4","printBackground":true}' \
  --output invoice.pdf