# 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"`](/parameters/format/) 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:

```bash
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:

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

### Return a PDF URL directly

Set `format` to `pdf` when creating the image:

```bash
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:

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

Requesting that URL renders and returns the separately saved PDF.

### Letter size with margins

```json
{
  "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

```json
{
  "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:

```json
{
  "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

```json
{
  "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

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

### Reports

```json
{
  "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:

```css
@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` |

Tip

For print documents, use inches (`in`) or millimeters (`mm`) for more accurate sizing.

## Need help?

Talk to a human. Email [support@htmlcsstoimage.com](mailto:support@htmlcsstoimage.com) and we’ll help you get started.