Generate PDF

Generate PDF

Generate a PDF from HTML, templates, or markdown using the /v1/pdf/generate endpoint.

Endpoint

POST https://lightningpdf.dev/api/v1/pdf/generate

Request Body

Basic HTML Generation

{
  "html": "<h1>Invoice</h1><p>Total: $100</p>"
}

Using Templates

{
  "template_id": "tpl_abc123",
  "variables": {
    "customer_name": "John Doe",
    "amount": 100,
    "items": [
      { "name": "Widget", "price": 50 },
      { "name": "Gadget", "price": 50 }
    ]
  }
}

With Options

{
  "html": "<h1>Report</h1>",
  "options": {
    "format": "A4",
    "print_background": true,
    "margin": {
      "top": "1in",
      "right": "0.5in",
      "bottom": "1in",
      "left": "0.5in"
    },
    "landscape": false,
    "display_header_footer": true,
    "header_template": "<div style='font-size: 10px; text-align: center;'>Page <span class='pageNumber'></span></div>",
    "footer_template": "<div style='font-size: 10px; text-align: center;'>© 2024 Company</div>"
  },
  "engine": "chromium"
}

Parameters

Parameter Type Required Description
html string Conditional* Raw HTML content to convert
template_id string Conditional* Template ID (starts with tpl_)
variables object No Variables to inject into template
options object No PDF generation options
engine string No Rendering engine: auto, native, chromium (default: auto)

* Either html or template_id is required

Options Object

Option Type Default Description
format string "A4" Paper format: A4, Letter, Legal, A3, A5, Tabloid
width string - Paper width (e.g., "8.5in", "210mm") overrides format
height string - Paper height (e.g., "11in", "297mm") overrides format
print_background boolean true Include background colors and images
landscape boolean false Landscape orientation
margin object {"top": "0.4in", ...} Page margins
display_header_footer boolean false Show header and footer
header_template string - HTML for header (supports <span class='pageNumber'>)
footer_template string - HTML for footer (supports <span class='pageNumber'>)
prefer_css_page_size boolean false Use CSS @page size
scale number 1.0 Scale factor (0.1 to 2.0)

Margin Object

{
  "top": "1in",
  "right": "0.5in",
  "bottom": "1in",
  "left": "0.5in"
}

Units: px, in, cm, mm

Engine Selection

  • auto (default): LightningPDF chooses the best engine based on HTML complexity
  • native: Fast, lightweight rendering (best for simple HTML)
  • chromium: Full browser rendering (supports modern CSS, flexbox, grid, JavaScript)
{
  "html": "<div style='display: grid;'>...</div>",
  "engine": "chromium"
}

Response

{
  "success": true,
  "data": {
    "pdf": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PmVuZG9iagoyIDAgb2JqPDwvVHlwZS9QYWdlcy9LaWRzWzMgMCBSXS9Db3VudCAxPj5lbmRvYmoK...",
    "generation_time_ms": 187,
    "engine_used": "chromium"
  }
}

Response Fields

Field Type Description
pdf string Base64-encoded PDF file
generation_time_ms integer Generation time in milliseconds
engine_used string Actual engine used (native or chromium)

Examples

Complete Invoice Example

import requests
import base64

def generate_invoice(customer, items, total):
    html = f"""
    <!DOCTYPE html>
    <html>
    <head>
      <style>
        body {{ font-family: Arial, sans-serif; margin: 2cm; }}
        .header {{ text-align: center; margin-bottom: 2cm; }}
        .invoice-table {{ width: 100%; border-collapse: collapse; }}
        .invoice-table th, .invoice-table td {{
          border: 1px solid #ddd;
          padding: 8px;
          text-align: left;
        }}
        .total {{ text-align: right; font-size: 18px; margin-top: 1cm; }}
      </style>
    </head>
    <body>
      <div class="header">
        <h1>INVOICE</h1>
        <p>Customer: {customer}</p>
      </div>
      <table class="invoice-table">
        <thead>
          <tr>
            <th>Item</th>
            <th>Quantity</th>
            <th>Price</th>
          </tr>
        </thead>
        <tbody>
          {''.join(f"<tr><td>{item['name']}</td><td>{item['qty']}</td><td>${item['price']}</td></tr>" for item in items)}
        </tbody>
      </table>
      <div class="total">
        <strong>Total: ${total}</strong>
      </div>
    </body>
    </html>
    """

    response = requests.post(
        "https://lightningpdf.dev/api/v1/pdf/generate",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "html": html,
            "options": {
                "format": "Letter",
                "print_background": True
            },
            "engine": "chromium"
        }
    )

    result = response.json()
    if result["success"]:
        pdf_bytes = base64.b64decode(result["data"]["pdf"])
        return pdf_bytes
    else:
        raise Exception(result["error"]["message"])

Using CSS Grid and Flexbox

curl -X POST https://lightningpdf.dev/api/v1/pdf/generate \
  -H "Authorization: Bearer lpdf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<div style=\"display: grid; grid-template-columns: 1fr 1fr; gap: 20px;\"><div>Left</div><div>Right</div></div>",
    "engine": "chromium"
  }'

{
  "html": "<h1>Multi-page Document</h1><p>Content...</p>",
  "options": {
    "display_header_footer": true,
    "header_template": "<div style='font-size: 9px; width: 100%; text-align: center;'><span class='title'></span></div>",
    "footer_template": "<div style='font-size: 9px; width: 100%; text-align: center;'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>",
    "margin": {
      "top": "1in",
      "bottom": "1in"
    }
  }
}

Error Codes

Code Description
invalid_html HTML content is missing or invalid
template_not_found Template ID does not exist
invalid_options Options object contains invalid values
generation_failed PDF generation failed (check HTML syntax)
insufficient_credits Not enough credits remaining

Rate Limits

  • Free: 100 requests/day
  • Starter: 2,000 requests/day
  • Pro: 10,000 requests/day
  • Business: 50,000 requests/day
  • Enterprise: 150,000 requests/day

Rate limit headers included in every response:

  • X-Credits-Remaining: Credits left in current period
  • X-RateLimit-Reset: Timestamp when credits reset