Request Schema

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

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.

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

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:

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

{
  "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"
}

Getting Started

Guides

Reference

Required parameters

Content parameters

Page layout

Text styling

Natural effects

Word rotation

Natural variation

Random indentation

Ink flow

Output options

PDF options

Address mode constraints

DPI scaling

Complete example

​Required parameters

​Content parameters

​Page layout

​Text styling

​Natural effects

​Word rotation

​Natural variation

​Random indentation

​Ink flow

​Output options

​PDF options

​Address mode constraints

​DPI scaling

​Complete example

Required parameters

Content parameters

Page layout

Text styling

Natural effects

Word rotation

Natural variation

Random indentation

Ink flow

Output options

PDF options

Address mode constraints

DPI scaling

Complete example