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

> Generate a high-quality PNG with a transparent background.

Use `POST /api/v1/generate` with `output_format: "png"` (default).

## Minimal request

```json theme={null}
{
  "text": "Hello!",
  "font_id": 1,
  "font_size": "auto",
  "page_size": "a4",
  "dpi": 300
}
```

## Response

The response is JSON:

```json theme={null}
{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "image_base64": "iVBORw0KGgoAAAANS...",
  "width": 2480,
  "height": 3508,
  "calculated_font_size": 42,
  "processing_time_ms": 523.7,
  "characters_processed": 150
}
```

| Field                  | Description                                                                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `request_id`           | Unique identifier for this request (use for support)                                                                                             |
| `image_base64`         | Base64-encoded PNG with transparent background                                                                                                   |
| `width`, `height`      | Pixel dimensions of the generated page                                                                                                           |
| `calculated_font_size` | The font size used (returned when `font_size: "auto"`)                                                                                           |
| `processing_time_ms`   | Server processing time in milliseconds                                                                                                           |
| `characters_processed` | Number of characters in your submitted text (after API normalization). Useful for debugging/metrics (billing is per request, not per character). |

## Tips

* Use `max_auto_font_size` to prevent overly large text for very short content.
* If you render at `dpi: 600`, keep setting margins/sizes as if they were **300 DPI** — the server scales them automatically.
* The renderer outputs **one page** (no pagination). Choose `page_size` + margins accordingly.