> ## 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. # 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 ## OpenAPI ````yaml https://api.handtextai.com/openapi.json post /api/v1/generate openapi: 3.1.0 info: title: HandTextAI API description: > # HandTextAI API Documentation Transform text into realistic handwriting for automated letter generation. > Full documentation: https://docs.handtextai.com ## Getting Started 1. **Authentication**: Include your API key in the Authorization header 2. **Test with preview**: Use `/preview` for watermarked samples 3. **Generate**: Use `/generate` for full-quality PNG or PDF ## Quick Example ### Python ```python import requests import base64 API_KEY = "htext_your_api_key" API_URL = "https://api.handtextai.com/api/v1" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } # Generate handwriting with auto font sizing response = requests.post( f"{API_URL}/generate", headers=headers, json={ "text": "Hello World!", "font_id": 1, "font_size": "auto", # Automatically calculates optimal size "page_size": "a4" } ) if response.status_code == 200: data = response.json() # Save image image_data = base64.b64decode(data["image_base64"]) with open("output.png", "wb") as f: f.write(image_data) ``` ### Python (PDF) ```python import requests API_KEY = "htext_your_api_key" API_URL = "https://api.handtextai.com/api/v1" headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", } # Generate a Lob-compatible PDF/X-1a (strict preflight, CMYK, no transparency) response = requests.post( f"{API_URL}/generate", headers=headers, json={ "text": "Hello from HandTextAI!", "font_id": 1, "font_size": "auto", "page_size": "letter", "dpi": 300, "output_format": "pdf", "pdf": { "preset": "lob" } }, ) if response.status_code == 200: with open("output.pdf", "wb") as f: f.write(response.content) ``` ### cURL ```bash curl -X POST https://api.handtextai.com/api/v1/generate \ -H "Authorization: Bearer htext_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "text": "Hello World!", "font_id": 1, "font_size": "auto", "page_size": "a4" }' ``` ### cURL (PDF) ```bash curl -X POST https://api.handtextai.com/api/v1/generate \ -H "Authorization: Bearer htext_your_api_key" \ -H "Content-Type: application/json" \ -o output.pdf \ -d '{ "text": "Hello World!", "font_id": 1, "font_size": "auto", "page_size": "postcard_us", "output_format": "pdf" }' ``` ## Features - 90 handwriting fonts optimized for printing - Automatic font sizing to fit your text perfectly - 15 page formats including standard paper sizes and envelopes - Natural handwriting effects (rotation, ink flow, variation) - Free watermarked preview generation - Address generation mode for envelope addressing ## Output Formats ### PNG (default) `output_format: "png"` returns JSON with `image_base64` (PNG, transparent background). ### PDF `output_format: "pdf"` returns a binary `application/pdf` response (white background only). PDF output supports: - Correct physical page size (based on the page size registry) - 300 or 600 DPI effective resolution (based on the rendered raster) - `MediaBox`/`TrimBox`/`BleedBox`/`CropBox` for prepress workflows - PDF/X-1a (CMYK) output for strict upload/preflight systems (via `pdf.preset="lob"` or `pdf.standard="pdfx1a"`) - Provider presets (via `pdf.preset`), e.g. `lob` and `click2mail` **PDF options** (the `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) - `region`: `auto` (default), `us`, `eu` - `bleed_mm`: override bleed in mm (optional) - `crop_box`: `media` (default), `bleed`, `trim` (standard PDF only) ## Page Sizes (15 Formats) All dimensions are shown in portrait orientation. Use `orientation: "landscape"` to swap width/height. ### ISO A-Series (Europe/International) | Size | Dimensions (mm) | Dimensions (inches) | Dimensions (pixels @ 300dpi) | |------|----------------|---------------------|------------------------------| | **a3** | 297×420 | 11.69×16.54 | 3508×4961 | | **a4** | 210×297 | 8.27×11.69 | 2480×3508 | | **a5** | 148×210 | 5.83×8.27 | 1748×2480 | | **a6** | 105×148 | 4.13×5.83 | 1240×1748 | ### US Standard Sizes | Size | Dimensions (mm) | Dimensions (inches) | Dimensions (pixels @ 300dpi) | |------|----------------|---------------------|------------------------------| | **letter** | 216×279 | 8.5×11 | 2550×3300 | | **legal** | 216×356 | 8.5×14 | 2550×4200 | | **half_letter** | 140×216 | 5.5×8.5 | 1650×2550 | ### Cards & Postcards | Size | Dimensions (mm) | Dimensions (inches) | Dimensions (pixels @ 300dpi) | |------|----------------|---------------------|------------------------------| | **postcard_us** | 102×152 | 4×6 | 1200×1800 | | **card_5x7** | 127×178 | 5×7 | 1500×2100 | | **card_a2** | 108×140 | 4.25×5.5 | 1275×1650 | | **square_5x5** | 127×127 | 5×5 | 1500×1500 | | **card_96x135** | 96×135 | 3.8×5.3 | 1134×1594 | ### Envelopes | Size | Dimensions (mm) | Dimensions (inches) | Dimensions (pixels @ 300dpi) | |------|----------------|---------------------|------------------------------| | **dl** | 99×210 | 3.9×8.27 | 1169×2480 | | **envelope_10** | 104.8×241.3 | 4.125×9.5 | 1238×2850 | | **envelope_monarch** | 98.4×190.5 | 3.875×7.5 | 1163×2250 | ## Generation Types ### Standard Generation Default mode for cards, letters, and general text: - Auto font sizing available - Full range of effects and customization ### Address Generation Optimized mode for envelope addressing: - Maximum 5 lines of text - Maximum 250 characters - Manual font sizing required (auto not supported) ## Authentication All endpoints except `/api/v1/status` require authentication via API key: ```http Authorization: Bearer htext_your_api_key_here ``` ## Support & Legal - **API Support**: api@handtextai.com - **Dashboard**: https://dashboard.handtextai.com - **Terms of Service**: [View Terms](/legal/terms) - **Privacy Policy**: [View Privacy Policy](/legal/privacy) contact: name: API Support email: api@handtextai.com license: name: Proprietary url: https://api.handtextai.com/legal/terms version: 1.0.0 servers: - url: https://api.handtextai.com description: Production API security: [] tags: - name: Endpoints description: Core endpoints for generating handwritten text paths: /api/v1/generate: post: tags: - Endpoints summary: Generate Handwritten Text description: >- 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 operationId: generate_endpoint_api_v1_generate_post requestBody: content: application/json: schema: $ref: '#/components/schemas/GenerateRequest' required: true responses: '200': description: Output generated successfully content: application/json: schema: $ref: '#/components/schemas/GenerateResponse' example: request_id: 550e8400-e29b-41d4-a716-446655440000 image_base64: iVBORw0KGgoAAAANS... width: 2100 height: 2970 processing_time_ms: 523.7 characters_processed: 150 application/pdf: schema: type: string format: binary '400': description: Invalid request parameters '401': description: Invalid or missing API key '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded '500': description: Generation error security: - HTTPBearer: [] components: schemas: GenerateRequest: properties: text: type: string maxLength: 10000 minLength: 1 title: Text description: Text to generate. Use \n for line breaks, \n\n for paragraphs. font_id: type: integer maximum: 90 minimum: 1 title: Font Id description: Font identifier (1-90). default: 1 font_size: anyOf: - type: integer - type: string const: auto title: Font Size description: Font size in pixels (12-400) or 'auto' for automatic sizing default: auto max_auto_font_size: anyOf: - type: integer maximum: 400 minimum: 20 - type: 'null' title: Max Auto Font Size description: >- 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. generation_type: type: string enum: - standard - address title: Generation Type description: >- 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) default: standard page_size: type: string enum: - 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 title: Page Size description: |- 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. default: a4 orientation: type: string enum: - portrait - landscape title: Orientation description: Page orientation default: portrait output_format: type: string enum: - png - pdf title: Output Format description: >- Output format. 'png' returns the current JSON response with base64 image. 'pdf' returns a binary application/pdf response. default: png pdf: anyOf: - $ref: '#/components/schemas/PdfOptions' - type: 'null' description: PDF-specific options (only used when output_format='pdf'). dpi: type: integer enum: - 300 - 600 title: Dpi description: >- 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. default: 300 line_height_multiplier: type: number maximum: 4 minimum: 0.5 title: Line Height Multiplier description: Line height as multiplier of font size default: 2 line_break_spacing: anyOf: - type: integer maximum: 500 minimum: 0 - type: 'null' title: Line Break Spacing description: Spacing between paragraphs in pixels at 300 DPI (None = auto) margin_left: type: integer maximum: 5000 minimum: 0 title: Margin Left description: Left margin in pixels at 300 DPI (240px = ~20mm) default: 240 margin_right: type: integer maximum: 5000 minimum: 0 title: Margin Right description: Right margin in pixels at 300 DPI (240px = ~20mm) default: 240 margin_top: type: integer maximum: 5000 minimum: 0 title: Margin Top description: Top margin in pixels at 300 DPI (240px = ~20mm) default: 240 margin_bottom: type: integer maximum: 5000 minimum: 0 title: Margin Bottom description: Bottom margin in pixels at 300 DPI (240px = ~20mm) default: 240 word_spacing: type: integer maximum: 3000 minimum: 0 title: Word Spacing description: Extra pixels between words at 300 DPI default: 0 enable_word_rotation: type: boolean title: Enable Word Rotation description: Enable word rotation effect default: false word_rotation_range: type: number maximum: 10 minimum: 0 title: Word Rotation Range description: Maximum rotation angle for words (default 5.0 when rotation enabled) default: 5 enable_natural_variation: type: boolean title: Enable Natural Variation description: Enable natural handwriting variation default: false natural_variation_alpha: type: integer maximum: 100 minimum: 0 title: Natural Variation Alpha description: >- 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. default: 15 natural_variation_sigma: type: integer maximum: 10 minimum: 0 title: Natural Variation Sigma description: >- Smoothness of deformation (default 5 when variation enabled). Values below 3 can look grainy; for high intensity (alpha), increase sigma to keep strokes smooth. default: 5 enable_random_indentation: type: boolean title: Enable Random Indentation description: Enable random line indentation default: false indentation_range: type: integer maximum: 100 minimum: 0 title: Indentation Range description: >- Range for random indentation in pixels at 300 DPI (default 20 when indentation enabled) default: 20 enable_ink_flow: type: boolean title: Enable Ink Flow description: Enable ink flow (fade text) effect default: false ink_flow_intensity: type: number maximum: 3 minimum: 0 title: Ink Flow Intensity description: >- Intensity of ink flow effect (default 1.0 when ink flow enabled, max 3.0) default: 1 text_alignment: type: string enum: - left - center title: Text Alignment description: Text alignment default: left kerning: type: boolean title: Kerning description: >- 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. default: true text_color: anyOf: - items: type: integer type: array maxItems: 3 minItems: 3 - type: 'null' title: Text Color description: RGB color for text type: object required: - text title: GenerateRequest description: Request model for generating handwritten text. GenerateResponse: properties: request_id: type: string title: Request Id description: Unique request identifier image_base64: type: string title: Image Base64 description: Base64 encoded PNG image width: type: integer title: Width description: Image width in pixels height: type: integer title: Height description: Image height in pixels calculated_font_size: anyOf: - type: integer - type: 'null' title: Calculated Font Size description: >- Actual font size used (populated when font_size='auto', None for manual sizing) processing_time_ms: type: number title: Processing Time Ms description: Processing time in milliseconds characters_processed: type: integer title: Characters Processed description: Number of characters processed type: object required: - request_id - image_base64 - width - height - processing_time_ms - characters_processed title: GenerateResponse description: Response model for generated handwritten text. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PdfOptions: properties: preset: type: string enum: - generic - lob - click2mail title: Preset description: >- Convenience preset for common print/mail providers. 'generic' uses standard PDF output. 'lob' targets Lob preflight compatibility (PDF/X-1a, no crop marks). 'click2mail' targets Click2Mail upload compatibility (no crop marks; bleed defaults may differ). default: generic standard: type: string enum: - pdf - pdfx1a title: Standard description: >- PDF standard. 'pdf' produces a standard PDF (RGB, white background). 'pdfx1a' produces a PDF/X-1a:2001 compliant CMYK PDF (no transparency), intended for strict preflight systems. default: pdf icc_profile: type: string enum: - auto - gracol_2013 - gracol_2006 - pso_coated_v3 - iso_coated_v2 title: Icc Profile description: >- Output intent / CMYK ICC profile for PDF/X-1a. 'auto' chooses a sensible default by region ('us' -> GRACoL 2013, 'eu' -> PSO Coated v3). default: auto profile: type: string enum: - auto - document - press title: Profile description: >- PDF layout profile. 'document' uses the selected page size as-is (no bleed, no crop marks). 'press' adds bleed and crop marks with correct PDF page boxes (for print shops that accept marks). 'auto' is a convenience option that may choose 'press' for trimmed products. default: document region: type: string enum: - auto - us - eu title: Region description: >- Region used for press defaults (bleed and crop mark conventions). 'auto' chooses based on page_size (e.g., ISO sizes -> eu, US sizes -> us). default: auto bleed_mm: anyOf: - type: number maximum: 20 minimum: 0 - type: 'null' title: Bleed Mm description: >- Bleed in millimeters (e.g., 3.0mm EU or 3.175mm US). If omitted, defaults are applied based on preset/page type and region. crop_box: type: string enum: - media - bleed - trim title: Crop Box description: >- Which PDF box to set as CropBox. 'media' keeps crop marks visible in PDF viewers; 'bleed' crops to BleedBox; 'trim' crops to TrimBox. default: media type: object title: PdfOptions description: Options for PDF output when output_format='pdf'. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: HTTPBearer: type: http scheme: bearer ````