> ## Documentation Index
> Fetch the complete documentation index at: https://docs.handtextai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PDF & Prepress

> Understanding PDF output options, presets, and print-ready settings.

When generating PDF output (`output_format: "pdf"`), you can configure prepress settings for professional printing.

## Quick start

For most use cases, one of the presets handles everything:

```json theme={null}
{
  "text": "Hello!",
  "font_id": 1,
  "page_size": "postcard_us",
  "output_format": "pdf",
  "pdf": {
    "preset": "generic"
  }
}
```

***

## Presets

Presets bundle common settings for specific use cases.

### `generic` (default)

Standard PDF output for most uses:

* RGB color space
* White background (no transparency)
* Bleed/crop marks are controlled by `pdf.profile` (defaults to `document`)

**Use for:** General downloads, archiving, non-print workflows.

<Tip>
  If you want the API to automatically choose `press` for trimmed products (postcards/cards) and `document` for letters, set `pdf.profile: "auto"`.
</Tip>

### `lob`

Optimized for [Lob.com](https://lob.com) print API:

* Forces PDF/X-1a (CMYK)
* Includes bleed on trimmed products (postcards, cards)
* No crop marks (Lob handles trimming)
* GRACoL 2013 ICC profile (US), PSO Coated v3 (EU)

**Use for:** Lob.com direct mail integration.

```json theme={null}
{
  "output_format": "pdf",
  "pdf": {
    "preset": "lob"
  }
}
```

### `click2mail`

Optimized for [Click2Mail](https://click2mail.com):

* Standard PDF (not PDF/X-1a)
* No crop marks or slug (clean edges)
* Larger bleed for US trimmed products (6.35mm / 0.25")
* Press profile for postcards, document profile for letters

**Use for:** Click2Mail portal uploads.

```json theme={null}
{
  "output_format": "pdf",
  "pdf": {
    "preset": "click2mail"
  }
}
```

***

## PDF standards

### `pdf` (default)

Standard PDF with RGB color:

* Compatible with all PDF viewers
* White background
* Supports profile/region/bleed options

### `pdfx1a`

PDF/X-1a:2001 for strict print preflight:

* CMYK color only (Ghostscript conversion)
* No transparency
* Embedded ICC profile
* Required by some commercial printers

```json theme={null}
{
  "pdf": {
    "standard": "pdfx1a"
  }
}
```

<Note>
  The `lob` preset automatically sets `standard: "pdfx1a"`. You don't need to specify both.
</Note>

***

## ICC profiles

For PDF/X-1a output, choose an ICC profile for color conversion:

| Profile         | Region | Description                              |
| --------------- | ------ | ---------------------------------------- |
| `auto`          | —      | US → GRACoL 2013, EU → PSO Coated v3     |
| `gracol_2013`   | US     | GRACoL 2013 (recommended for US print)   |
| `gracol_2006`   | US     | Legacy GRACoL 2006                       |
| `pso_coated_v3` | EU     | PSO Coated v3 (recommended for EU print) |
| `iso_coated_v2` | EU     | ISO Coated v2 (alternative EU profile)   |

```json theme={null}
{
  "pdf": {
    "standard": "pdfx1a",
    "icc_profile": "gracol_2013"
  }
}
```

***

## Profiles

For standard PDF output, the profile controls bleed and crop marks:

### `document`

Clean page with no print production marks:

* No bleed area
* No crop marks
* Page size matches paper size exactly

This is the default (`pdf.profile` defaults to `document`).

### `auto`

Automatically chooses a sensible profile based on page size:

* `press` for trimmed products: `postcard_us`, `card_5x7`, `card_a2`, `square_5x5`, `card_96x135`
* `document` for letters/envelopes and other formats

```json theme={null}
{
  "pdf": {
    "profile": "auto"
  }
}
```

### `press`

Print-ready with bleed and trim guides:

* Includes bleed area around content
* Adds crop marks for trimming
* Includes slug area for marks

Use this when you need print production marks and bleed (common for postcards/cards).

```json theme={null}
{
  "pdf": {
    "profile": "press"
  }
}
```

***

## Bleed settings

Bleed is extra content area that extends beyond the trim line, ensuring no white edges after cutting.

### Regional defaults

When profile is `press` and bleed is not specified:

| Region | Default bleed      |
| ------ | ------------------ |
| US     | 3.175mm (1/8 inch) |
| EU     | 3.0mm              |

### Custom bleed

Override with `bleed_mm`:

```json theme={null}
{
  "pdf": {
    "profile": "press",
    "bleed_mm": 5.0
  }
}
```

***

## Region

Region affects default bleed, ICC profile selection, and crop mark style:

| Region | Bleed          | ICC Profile   | Crop marks  |
| ------ | -------------- | ------------- | ----------- |
| `us`   | 1/8" (3.175mm) | GRACoL 2013   | 1/4" length |
| `eu`   | 3mm            | PSO Coated v3 | 5mm length  |

### Auto-detection

When `region: "auto"` (default):

* ISO sizes (`a3`, `a4`, `a5`, `a6`, `dl`, `card_96x135`) → `eu`
* US sizes (`letter`, `legal`, `postcard_us`, etc.) → `us`

***

## Crop box

Controls the visible area in PDF viewers:

| Value   | Description                                      |
| ------- | ------------------------------------------------ |
| `media` | Shows entire page including crop marks (default) |
| `bleed` | Crops to BleedBox (hides marks, shows bleed)     |
| `trim`  | Crops to TrimBox (final product size)            |

```json theme={null}
{
  "pdf": {
    "profile": "press",
    "crop_box": "trim"
  }
}
```

***

## PDF boxes explained

PDF prepress uses several box definitions:

```
┌─────────────────────────────────┐
│  MediaBox (full page + marks)   │
│  ┌────────────────────────┐     │
│  │  BleedBox (+ bleed)    │     │
│  │  ┌─────────────────┐   │     │
│  │  │  TrimBox        │   │     │
│  │  │  (final size)   │   │     │
│  │  │                 │   │     │
│  │  └─────────────────┘   │     │
│  └────────────────────────┘     │
└─────────────────────────────────┘
```

* **TrimBox**: The intended final product size
* **BleedBox**: TrimBox plus bleed area
* **MediaBox**: Full page including crop marks and slug

***

## Examples

### Postcard for Lob

```json theme={null}
{
  "text": "Thank you for your order!",
  "font_id": 1,
  "page_size": "postcard_us",
  "output_format": "pdf",
  "pdf": {
    "preset": "lob"
  }
}
```

### A4 letter for download

```json theme={null}
{
  "text": "Dear valued customer...",
  "font_id": 2,
  "page_size": "a4",
  "output_format": "pdf"
}
```

### Press-ready greeting card

```json theme={null}
{
  "text": "Happy Birthday!",
  "font_id": 3,
  "page_size": "card_5x7",
  "output_format": "pdf",
  "pdf": {
    "profile": "press",
    "region": "us",
    "bleed_mm": 3.175
  }
}
```