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