> ## 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.

# Request Schema

> Complete reference for all request parameters.

All parameters for `POST /api/v1/generate` and `POST /api/v1/preview`.

<Note>
  All pixel values (margins, font sizes, spacing) are specified at **300 DPI baseline**. When using `dpi: 600`, the API automatically scales them to maintain physical dimensions.
</Note>

***

## Required parameters

| Parameter | Type   | Description                                                                           |
| --------- | ------ | ------------------------------------------------------------------------------------- |
| `text`    | string | Text to render. 1-10,000 characters. Use `\n` for line breaks, `\n\n` for paragraphs. |

***

## Content parameters

| Parameter            | Type            | Default      | Range  | Description                                                                 |
| -------------------- | --------------- | ------------ | ------ | --------------------------------------------------------------------------- |
| `font_id`            | integer         | `1`          | 1-90   | Font identifier. See [fonts guide](/guides/fonts).                          |
| `font_size`          | int or `"auto"` | `"auto"`     | 12-400 | Font size in pixels, or `"auto"` for automatic sizing.                      |
| `max_auto_font_size` | integer         | `200`        | 20-400 | Maximum size when using auto-fit. Prevents oversized text on short content. |
| `generation_type`    | string          | `"standard"` | —      | `"standard"` or `"address"`. Address mode has constraints (see below).      |

***

## Page layout

| Parameter       | Type    | Default      | Range    | Description                                                  |
| --------------- | ------- | ------------ | -------- | ------------------------------------------------------------ |
| `page_size`     | string  | `"a4"`       | —        | Page format. See [page sizes guide](/guides/page-sizes-dpi). |
| `orientation`   | string  | `"portrait"` | —        | `"portrait"` or `"landscape"`.                               |
| `dpi`           | integer | `300`        | 300, 600 | Output resolution.                                           |
| `margin_left`   | integer | `240`        | 0-5000   | Left margin in pixels (\~20mm at 300 DPI).                   |
| `margin_right`  | integer | `240`        | 0-5000   | Right margin in pixels.                                      |
| `margin_top`    | integer | `240`        | 0-5000   | Top margin in pixels.                                        |
| `margin_bottom` | integer | `240`        | 0-5000   | Bottom margin in pixels.                                     |

***

## Text styling

| Parameter                | Type    | Default  | Range      | Description                                              |
| ------------------------ | ------- | -------- | ---------- | -------------------------------------------------------- |
| `text_alignment`         | string  | `"left"` | —          | `"left"` or `"center"`.                                  |
| `text_color`             | array   | `null`   | 0-255 each | RGB color as `[R, G, B]` (defaults to black if omitted). |
| `kerning`                | boolean | `true`   | —          | Enable letter pair kerning for natural spacing.          |
| `line_height_multiplier` | float   | `2.0`    | 0.5-4.0    | Line height as multiplier of font size.                  |
| `line_break_spacing`     | integer | auto     | 0-500      | Extra spacing between paragraphs (after `\n\n`).         |
| `word_spacing`           | integer | `0`      | 0-3000     | Extra pixels between words.                              |

***

## Natural effects

All effects are disabled by default. Enable each with its boolean flag.

### Word rotation

| Parameter              | Type    | Default | Range | Description                          |
| ---------------------- | ------- | ------- | ----- | ------------------------------------ |
| `enable_word_rotation` | boolean | `false` | —     | Enable slight word angle variations. |
| `word_rotation_range`  | float   | `5.0`   | 0-10  | Maximum rotation angle in degrees.   |

### Natural variation

Elastic deformation that makes letters less uniform.

| Parameter                  | Type    | Default | Range | Description                                     |
| -------------------------- | ------- | ------- | ----- | ----------------------------------------------- |
| `enable_natural_variation` | boolean | `false` | —     | Enable letter displacement effect.              |
| `natural_variation_alpha`  | integer | `15`    | 0-100 | Deformation intensity. 10-40 typical.           |
| `natural_variation_sigma`  | integer | `5`     | 0-10  | Deformation smoothness. Use ≥3 with high alpha. |

### Random indentation

| Parameter                   | Type    | Default | Range | Description                         |
| --------------------------- | ------- | ------- | ----- | ----------------------------------- |
| `enable_random_indentation` | boolean | `false` | —     | Enable random line start variation. |
| `indentation_range`         | integer | `20`    | 0-100 | Maximum indentation in pixels.      |

### Ink flow

Simulates ink fading/running out.

| Parameter            | Type    | Default | Range | Description             |
| -------------------- | ------- | ------- | ----- | ----------------------- |
| `enable_ink_flow`    | boolean | `false` | —     | Enable ink fade effect. |
| `ink_flow_intensity` | float   | `1.0`   | 0-3.0 | Fade intensity.         |

***

## Output options

| Parameter       | Type   | Default | Description                                                                            |
| --------------- | ------ | ------- | -------------------------------------------------------------------------------------- |
| `output_format` | string | `"png"` | `"png"` (JSON with base64) or `"pdf"` (binary response).                               |
| `pdf`           | object | —       | PDF options (only when `output_format: "pdf"`). See [PDF guide](/guides/pdf-prepress). |

***

## PDF options

Only applies when `output_format: "pdf"`.

| Parameter         | Type   | Default      | Description                           |
| ----------------- | ------ | ------------ | ------------------------------------- |
| `pdf.preset`      | string | `"generic"`  | `"generic"`, `"lob"`, `"click2mail"`. |
| `pdf.standard`    | string | `"pdf"`      | `"pdf"` (RGB) or `"pdfx1a"` (CMYK).   |
| `pdf.icc_profile` | string | `"auto"`     | ICC profile for PDF/X-1a.             |
| `pdf.profile`     | string | `"document"` | `"document"`, `"press"`, `"auto"`.    |
| `pdf.region`      | string | `"auto"`     | `"us"`, `"eu"`, `"auto"`.             |
| `pdf.bleed_mm`    | float  | auto         | Bleed in mm (0-20).                   |
| `pdf.crop_box`    | string | `"media"`    | `"media"`, `"bleed"`, `"trim"`.       |

***

## Address mode constraints

When `generation_type: "address"`:

| Constraint         | Limit                     |
| ------------------ | ------------------------- |
| Maximum lines      | 5                         |
| Maximum characters | 250                       |
| Font sizing        | Manual only (no `"auto"`) |

Example:

```json theme={null}
{
  "text": "John Smith\n123 Main Street\nAnytown, ST 12345",
  "generation_type": "address",
  "font_size": 48,
  "page_size": "envelope_10"
}
```

***

## DPI scaling

All pixel values are at 300 DPI baseline. At 600 DPI:

| 300 DPI | 600 DPI | Physical |
| ------- | ------- | -------- |
| 240px   | 480px   | \~20mm   |
| 100px   | 200px   | \~8.5mm  |
| 1200px  | 2400px  | \~102mm  |

You don't need to change values when switching DPI — the API scales automatically.

***

## Complete example

```json theme={null}
{
  "text": "Dear valued customer,\n\nThank you for your order!",
  "font_id": 3,
  "font_size": "auto",
  "max_auto_font_size": 150,
  "page_size": "card_5x7",
  "orientation": "portrait",
  "dpi": 300,
  "margin_left": 180,
  "margin_right": 180,
  "margin_top": 200,
  "margin_bottom": 200,
  "text_alignment": "left",
  "text_color": [20, 20, 80],
  "kerning": true,
  "line_height_multiplier": 2.2,
  "enable_word_rotation": true,
  "word_rotation_range": 3.0,
  "enable_natural_variation": true,
  "natural_variation_alpha": 20,
  "natural_variation_sigma": 5,
  "output_format": "png"
}
```