pdf_options

Generate customized PDF documents from HTML

How it works

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:

Property	Type	Description
`page_width`	`String`	Width of the page with unit (px, in, cm, mm, pt). Example: `8.5in`
`page_height`	`String`	Height of the page with unit (px, in, cm, mm, pt). Example: `11in`
`scale`	`Number`	Scale of the webpage rendering. Range: `0.1` to `2`. Default: `1`
`margins`	`Array`	Page margins as 4 values: [top, right, bottom, left]. Example: `["1cm", "1cm", "1cm", "1cm"]`
`print_background`	`Boolean`	Whether to print background graphics. Default: `false`

Common page sizes

Size	Dimensions	Use Case
Letter	`8.5in` x `11in`	US standard documents
A4	`210mm` x `297mm`	International standard
Legal	`8.5in` x `14in`	Legal documents
A5	`148mm` x `210mm`	Smaller documents

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

Always set print_background if you have CSS backgrounds, gradients, or colors
Use appropriate margins for your content - typically 0.5-1 inch for printable documents
Test your page size before bulk generation
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:

Unit	Description	Example
`px`	Pixels	`612px`
`in`	Inches	`8.5in`
`cm`	Centimeters	`21cm`
`mm`	Millimeters	`210mm`
`pt`	Points (1/72 inch)	`72pt`

Need help?

Talk to a human. Email support@htmlcsstoimage.com and we’ll help you get started.