Generate Watermarked Preview

curl --request POST \
  --url https://api.handtextai.com/api/v1/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "<string>",
  "font_id": 1,
  "font_size": "auto",
  "max_auto_font_size": 210,
  "generation_type": "standard",
  "page_size": "a4",
  "orientation": "portrait",
  "output_format": "png",
  "pdf": {
    "preset": "generic",
    "standard": "pdf",
    "icc_profile": "auto",
    "profile": "document",
    "region": "auto",
    "bleed_mm": 10,
    "crop_box": "media"
  },
  "dpi": 300,
  "line_height_multiplier": 2,
  "line_break_spacing": 250,
  "margin_left": 240,
  "margin_right": 240,
  "margin_top": 240,
  "margin_bottom": 240,
  "word_spacing": 0,
  "enable_word_rotation": false,
  "word_rotation_range": 5,
  "enable_natural_variation": false,
  "natural_variation_alpha": 15,
  "natural_variation_sigma": 5,
  "enable_random_indentation": false,
  "indentation_range": 20,
  "enable_ink_flow": false,
  "ink_flow_intensity": 1,
  "text_alignment": "left",
  "kerning": true,
  "text_color": [
    123
  ]
}
'

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "image_base64": "iVBORw0KGgoAAAANS...",
  "width": 2100,
  "height": 2970,
  "preview_width": 1200,
  "preview_height": 1697,
  "processing_time_ms": 245.5
}

Endpoints

Generate Watermarked Preview

Generate a watermarked preview at 1200px width.

Note: Preview always returns PNG. output_format must be "png" (use /generate for PDF).

Perfect for:

Testing parameters before final generation
Previewing text layout and font appearance
Validating automatic font sizing

The preview is free, includes a watermark, and is scaled to 1200px width while maintaining aspect ratio.

Generation Types:

standard (default): For cards, letters, and general text
address: For envelope addresses with specific constraints (see below)

Address Generation Constraints: When using generation_type: "address", the following limitations apply:

Maximum 5 lines - Text cannot exceed 5 lines (separated by \n)
Maximum 250 characters - Total character limit including line breaks
Manual font sizing required - font_size: "auto" is not supported; you must specify a font size between 12-400 pixels

Text Formatting:

Use \n for line breaks
Use \n\n for paragraph spacing

POST

api

preview

Generate Watermarked Preview

curl --request POST \
  --url https://api.handtextai.com/api/v1/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "<string>",
  "font_id": 1,
  "font_size": "auto",
  "max_auto_font_size": 210,
  "generation_type": "standard",
  "page_size": "a4",
  "orientation": "portrait",
  "output_format": "png",
  "pdf": {
    "preset": "generic",
    "standard": "pdf",
    "icc_profile": "auto",
    "profile": "document",
    "region": "auto",
    "bleed_mm": 10,
    "crop_box": "media"
  },
  "dpi": 300,
  "line_height_multiplier": 2,
  "line_break_spacing": 250,
  "margin_left": 240,
  "margin_right": 240,
  "margin_top": 240,
  "margin_bottom": 240,
  "word_spacing": 0,
  "enable_word_rotation": false,
  "word_rotation_range": 5,
  "enable_natural_variation": false,
  "natural_variation_alpha": 15,
  "natural_variation_sigma": 5,
  "enable_random_indentation": false,
  "indentation_range": 20,
  "enable_ink_flow": false,
  "ink_flow_intensity": 1,
  "text_alignment": "left",
  "kerning": true,
  "text_color": [
    123
  ]
}
'

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "image_base64": "iVBORw0KGgoAAAANS...",
  "width": 2100,
  "height": 2970,
  "preview_width": 1200,
  "preview_height": 1697,
  "processing_time_ms": 245.5
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request model for generating handwritten text.

text

string

required

Text to generate. Use \n for line breaks, \n\n for paragraphs.

Required string length: 1 - 10000

font_id

integer

default:1

Font identifier (1-90).

Required range: 1 <= x <= 90

font_size

default:auto

Font size in pixels (12-400) or 'auto' for automatic sizing

max_auto_font_size

integer | null

Maximum font size for auto-fit mode in pixels (default: 200px). Only applies when font_size='auto'. Use to prevent oversized fonts on short text.

Required range: 20 <= x <= 400

generation_type

enum<string>

default:standard

Generation type. Options: 'standard' (default) for cards/letters/general text, 'address' for envelope addresses (max 5 lines, 250 chars, manual font sizing required - 'auto' not supported)

Available options:

standard,

address

page_size

enum<string>

default:a4

Page size for output. Common sizes with dimensions at 300 DPI:

a4: 2480×3508px (210×297mm) - Standard letter (Europe)
a6: 1240×1748px (105×148mm) - Postcards (Europe)
letter: 2550×3300px (216×279mm) - Standard letter (US)
postcard_us: 1200×1800px (102×152mm) - US Postcards
card_96x135: 1134×1594px (96×135mm) - Gift cards (3.8×5.3")
envelope_10: 1238×2850px (4.125×9.5") - US Business Envelope #10
envelope_monarch: 1163×2250px (3.875×7.5") - Monarch Envelope

See documentation for full list of sizes.

Available options:

a3,

a4,

a5,

a6,

A3,

A4,

A5,

A6,

letter,

legal,

half_letter,

postcard_us,

card_5x7,

card_a2,

square_5x5,

card_96x135,

dl,

envelope_10,

envelope_monarch

orientation

enum<string>

default:portrait

Page orientation

Available options:

portrait,

landscape

output_format

enum<string>

default:png

Output format. 'png' returns the current JSON response with base64 image. 'pdf' returns a binary application/pdf response.

Available options:

png,

pdf

pdf

PdfOptions · object

PDF-specific options (only used when output_format='pdf').

Show child attributes

dpi

enum<integer>

default:300

Output resolution in dots per inch. 300 DPI for standard printing, 600 DPI for high-quality printing. Note: All pixel values (margins, font sizes, spacing) are relative to 300 DPI and will be automatically scaled for other DPI values to maintain physical dimensions.

Available options:

300,

600

line_height_multiplier

number

default:2

Line height as multiplier of font size

Required range: 0.5 <= x <= 4

line_break_spacing

integer | null

Spacing between paragraphs in pixels at 300 DPI (None = auto)

Required range: 0 <= x <= 500

margin_left

integer

default:240

Left margin in pixels at 300 DPI (240px = ~20mm)

Required range: 0 <= x <= 5000

margin_right

integer

default:240

Right margin in pixels at 300 DPI (240px = ~20mm)

Required range: 0 <= x <= 5000

margin_top

integer

default:240

Top margin in pixels at 300 DPI (240px = ~20mm)

Required range: 0 <= x <= 5000

margin_bottom

integer

default:240

Bottom margin in pixels at 300 DPI (240px = ~20mm)

Required range: 0 <= x <= 5000

word_spacing

integer

default:0

Extra pixels between words at 300 DPI

Required range: 0 <= x <= 3000

enable_word_rotation

boolean

default:false

Enable word rotation effect

word_rotation_range

number

default:5

Maximum rotation angle for words (default 5.0 when rotation enabled)

Required range: 0 <= x <= 10

enable_natural_variation

boolean

default:false

Enable natural handwriting variation

natural_variation_alpha

integer

default:15

Intensity of elastic deformation (default 15 when variation enabled). Typical useful range is 10–40; higher values create stronger bending and should be paired with sigma ≥ 3.

Required range: 0 <= x <= 100

natural_variation_sigma

integer

default:5

Smoothness of deformation (default 5 when variation enabled). Values below 3 can look grainy; for high intensity (alpha), increase sigma to keep strokes smooth.

Required range: 0 <= x <= 10

enable_random_indentation

boolean

default:false

Enable random line indentation

indentation_range

integer

default:20

Range for random indentation in pixels at 300 DPI (default 20 when indentation enabled)

Required range: 0 <= x <= 100

enable_ink_flow

boolean

default:false

Enable ink flow (fade text) effect

ink_flow_intensity

number

default:1

Intensity of ink flow effect (default 1.0 when ink flow enabled, max 3.0)

Required range: 0 <= x <= 3

text_alignment

enum<string>

default:left

Text alignment

Available options:

left,

center

kerning

boolean

default:true

Enable kerning (automatic letter spacing adjustments based on character pairs). When enabled, letters like 'AV' or 'To' are positioned closer for natural appearance. Disable for uniform spacing between all letters.

text_color

integer[] | null

RGB color for text

Required array length: 3 elements

Response

Preview generated successfully

Response model for preview generation.

request_id

string

required

Unique request identifier

image_base64

string

required

Base64 encoded PNG image

width

integer

required

Original image width in pixels

height

integer

required

Original image height in pixels

preview_width

integer

required

Preview width (1200px)

preview_height

integer

required

Preview height maintaining aspect ratio

processing_time_ms

number

required

Processing time in milliseconds

calculated_font_size

integer | null

Actual font size used (populated when font_size='auto', None for manual sizing)

Generate Handwritten Text List Available Fonts