PDF Options

Generate customized PDF documents from HTML

Overview

When generating PDFs, use the pdf_options parameter to control page size, margins, scaling, and background printing.

You can use either of these flows:

• Create an image, then render it as a PDF: Create the image normally, then add .pdf to the returned image URL.
• Render it as a PDF directly: Include format: "pdf" when creating the image. The URL in the creation response will already end in .pdf.

In both cases, the PDF is rendered and saved separately when its URL is requested. The format parameter only controls the URL returned by the creation request; it does not change the stored image definition.

Parameters

The pdf_options object accepts the following properties:

Common page sizes

Example usage

Create an image, then render it as a PDF

Create an image and access it as PDF:

curl -X POST https://hcti.io/v1/image -u 'UserID:APIKey' \
     -H "Content-Type: application/json" \
     -d '{
       "html": "<h1>Invoice #1234</h1><p>Thank you for your purchase.</p>"
     }'

Then append .pdf to the returned URL:

https://hcti.io/v1/image/abc123.pdf

Return a PDF URL directly

Set format to pdf when creating the image:

curl -X POST https://hcti.io/v1/image -u 'UserID:APIKey' \
     -H "Content-Type: application/json" \
     -d '{
       "html": "<h1>Invoice #1234</h1><p>Thank you for your purchase.</p>",
       "format": "pdf",
       "pdf_options": {
         "print_background": true
       }
     }'

The response URL already includes the PDF extension:

{
  "url": "https://hcti.io/v1/image/abc123.pdf",
  "id": "abc123"
}

Requesting that URL renders and returns the separately saved PDF.

Letter size with margins

{
  "html": "<div class='invoice'>...</div>",
  "pdf_options": {
    "page_width": "8.5in",
    "page_height": "11in",
    "margins": ["0.5in", "0.5in", "0.5in", "0.5in"],
    "print_background": true
  }
}

A4 document

{
  "html": "<div class='report'>...</div>",
  "pdf_options": {
    "page_width": "210mm",
    "page_height": "297mm",
    "margins": ["20mm", "15mm", "20mm", "15mm"],
    "print_background": true
  }
}

Scaled content

If your HTML is too large for the page, use scale to fit:

{
  "html": "<div style='width: 1200px'>Wide content...</div>",
  "pdf_options": {
    "page_width": "8.5in",
    "page_height": "11in",
    "scale": 0.75,
    "print_background": true
  }
}

Common use cases

Invoices and receipts

{
  "html": "<div class='invoice'><h1>Invoice</h1>...</div>",
  "css": ".invoice { font-family: Arial; padding: 40px; }",
  "pdf_options": {
    "page_width": "8.5in",
    "page_height": "11in",
    "margins": ["0.75in", "0.75in", "0.75in", "0.75in"],
    "print_background": true
  }
}

Certificates

{
  "html": "<div class='certificate'>...</div>",
  "css": ".certificate { background: linear-gradient(...); }",
  "pdf_options": {
    "page_width": "11in",
    "page_height": "8.5in",
    "print_background": true
  }
}

Reports

{
  "html": "<div class='report'><h1>Monthly Report</h1>...</div>",
  "pdf_options": {
    "page_width": "210mm",
    "page_height": "297mm",
    "margins": ["25mm", "20mm", "25mm", "20mm"],
    "print_background": true
  }
}

Best practices

1. Always set print_background if you have CSS backgrounds, gradients, or colors
2. Use appropriate margins for your content - typically 0.5-1 inch for printable documents
3. Test your page size before bulk generation
4. Use print media queries in your CSS for optimal PDF styling:

@media print {
  .no-print { display: none; }
  body { font-size: 12pt; }
}

Units

All size values support these units:

Need help?

We’re always looking to improve this documentation. Please send us an email: support@htmlcsstoimage.com. We respond fast.