Python HTML to PDF API guide
Use Python requests to generate PDFs from Django, Flask, FastAPI, notebooks, or batch scripts.
Overview
Post JSON to the HTML to PDF API, validate the HTTP status code, and write the PDF bytes to disk.
The API accepts a JSON request body. Send either a public URL or inline HTML in the required html parameter. For normal synchronous conversions, the response body is the generated PDF and should be saved as binary data.
Requirements
- Python 3.10 or newer
- The requests package
- An html2pdf.app API key in an environment variable
Quick start
Replace <your-api-key> or the environment variable with your html2pdf.app API key, then run the example from a trusted backend environment.
This script converts a public URL and writes the binary response to document.pdf.
import os
from pathlib import Path
import requests
response = requests.post(
"https://api.html2pdf.app/v1/generate",
json={"html": "https://www.example.com"},
headers={"X-API-Key": os.environ["HTML2PDF_API_KEY"]},
timeout=60,
)
response.raise_for_status()
Path("document.pdf").write_bytes(response.content)Python examples
These examples cover the next common production flows: generating from inline HTML with options and queuing a callback job.
1. Generate from inline HTML with options
Use inline HTML when your application renders the document content itself.
import os
from pathlib import Path
import requests
payload = {
"html": "<h1>Invoice</h1><p>Total: $240.00</p>",
"format": "A4",
"media": "print",
"marginTop": 40,
"marginRight": 32,
"marginBottom": 40,
"marginLeft": 32,
"filename": "invoice.pdf",
}
response = requests.post(
"https://api.html2pdf.app/v1/generate",
json=payload,
headers={"X-API-Key": os.environ["HTML2PDF_API_KEY"]},
timeout=60,
)
response.raise_for_status()
Path("invoice.pdf").write_bytes(response.content)2. Submit an asynchronous conversion
Send callBackUrl and state to receive the generated PDF in a later webhook request.
import os
import requests
payload = {
"html": "https://www.example.com/report",
"callBackUrl": "https://your-app.com/webhooks/html2pdf",
"state": "report-1042",
}
response = requests.post(
"https://api.html2pdf.app/v1/generate",
json=payload,
headers={"X-API-Key": os.environ["HTML2PDF_API_KEY"]},
timeout=30,
)
response.raise_for_status()Request options
Most integrations start with html and then add options as the document design becomes more specific.
htmlis required and accepts a public URL or raw HTML.format,landscape,width, andheightcontrol page size.marginTop,marginRight,marginBottom, andmarginLeftcontrol whitespace around the rendered page.mediaselectsscreenorprintCSS rendering.callBackUrlswitches the request to asynchronous generation and sends the completed PDF to your webhook.
See the full API parameter reference for every supported field.
Troubleshooting
- Install requests with pip install requests.
- Use response.content or Path.write_bytes for synchronous PDF responses.
- Use response.raise_for_status before writing the PDF file.
If the generated document is blank or missing styles, first confirm that the source URL is public and that required CSS, fonts, and images are reachable by the rendering service.