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

# List Available Fonts

> Get list of available handwriting fonts.

Returns the full handwriting font catalog (90 fonts), each optimized
for different styles and languages.



## OpenAPI

````yaml https://api.handtextai.com/openapi.json get /api/v1/fonts
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/fonts:
    get:
      tags:
        - Endpoints
      summary: List Available Fonts
      description: |-
        Get list of available handwriting fonts.

        Returns the full handwriting font catalog (90 fonts), each optimized
        for different styles and languages.
      operationId: list_fonts_api_v1_fonts_get
      responses:
        '200':
          description: List of available fonts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FontListResponse'
              example:
                fonts:
                  - id: 1
                    supported_languages:
                      - en
                      - de
                      - fr
                  - id: 2
                    supported_languages:
                      - en
                      - es
                      - it
        '401':
          description: Invalid or missing API key
        '429':
          description: Rate limit exceeded
      security:
        - HTTPBearer: []
components:
  schemas:
    FontListResponse:
      properties:
        fonts:
          items:
            $ref: '#/components/schemas/FontInfo'
          type: array
          title: Fonts
          description: List of available fonts
      type: object
      required:
        - fonts
      title: FontListResponse
      description: Response model for font list.
    FontInfo:
      properties:
        id:
          type: integer
          title: Id
          description: Font identifier (1-90)
        supported_languages:
          items:
            type: string
          type: array
          title: Supported Languages
          description: List of supported languages
      type: object
      required:
        - id
        - supported_languages
      title: FontInfo
      description: Font information model.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````