Generate Handwritten Text

curl --request POST \
  --url https://api.handtextai.com/api/v1/generate \
  --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": "<string>",
  "image_base64": "<string>",
  "width": 123,
  "height": 123,
  "processing_time_ms": 123,
  "characters_processed": 123,
  "calculated_font_size": 123
}

Endpoints

Generate Handwritten Text

Generate high-quality handwritten text image.

This endpoint generates a full-quality print-ready output.

Output formats

output_format: "png" (default): Returns JSON with a base64-encoded PNG (transparent background).
output_format: "pdf": Returns a binary application/pdf response (white background only).

Key Features:

Automatic font sizing with font_size: "auto"
Multiple page sizes (see documentation for pixel dimensions)
Natural handwriting effects
Transparent background for PNG overlay
PDF prepress boxes (MediaBox/TrimBox/BleedBox/CropBox) for print workflows
PDF/X-1a output for strict preflight systems (use pdf.preset="lob" or pdf.standard="pdfx1a")

PDF options (pdf object, only when output_format="pdf"):

preset: generic (default), lob (PDF/X-1a), click2mail (portal-friendly; disables marks/slug, sets postcard bleed defaults)
standard: pdf (default) or pdfx1a (CMYK PDF/X-1a:2001 via Ghostscript)
icc_profile: auto (default), gracol_2013, gracol_2006, pso_coated_v3, iso_coated_v2 (PDF/X-1a only)
profile: document (default), press, auto (standard PDF only; PDF/X-1a uses preset/standard rules)
region: auto (default), us, eu
bleed_mm: override bleed in mm (optional)
crop_box: media (default), bleed, trim (standard PDF only)

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

generate

Generate Handwritten Text

curl --request POST \
  --url https://api.handtextai.com/api/v1/generate \
  --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": "<string>",
  "image_base64": "<string>",
  "width": 123,
  "height": 123,
  "processing_time_ms": 123,
  "characters_processed": 123,
  "calculated_font_size": 123
}

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

Output generated successfully

Response model for generated handwritten text.

request_id

string

required

Unique request identifier

image_base64

string

required

Base64 encoded PNG image

width

integer

required

Image width in pixels

height

integer

required

Image height in pixels

processing_time_ms

number

required

Processing time in milliseconds

characters_processed

integer

required

Number of characters processed

calculated_font_size

integer | null

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

Generate Watermarked Preview