# Generate Images Instead of PDFs


PDFMonkey generates PDFs by default, but templates with the **Image** output type produce **WebP, PNG, or JPG images** instead. The API workflow is identical; only the template type and a few meta options differ.

## Creating an image template

To generate images, you need a template configured for image output. Select **Image** as the output type when creating your template:

> [!TIP]
> **Pro tip**
>
> You can also duplicate an existing template and change its output type to **Image**.


> [!NOTE]
> **Why separate template types?**
>
> PDFs and images have fundamentally different capabilities. PDF documents support headers, footers, and various paper sizes. Image templates support transparent backgrounds and pixel-based dimensions instead.


Once the template is created, open its settings to configure:

- **Width and height**: in pixels (defaults to 500 x 500)
- **Transparent background**: supported by WebP and PNG

## Generating an image via the API

Generate an image the same way you generate a PDF: send a `POST` request to `/api/v1/documents` (or `/api/v1/documents/sync` for [synchronous generation](../api/documents.md#synchronous-generation)). As long as the `document_template_id` points to an image template, PDFMonkey produces an image instead of a PDF.

```bash
curl https://api.pdfmonkey.io/api/v1/documents \
  -X POST \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "document": {
      "document_template_id": "YOUR_IMAGE_TEMPLATE_ID",
      "status": "pending",
      "payload": { "title": "Hello World" }
    }
  }'
```

By default, a **WebP** image is created. WebP offers good quality at a reasonable file size and supports transparent backgrounds.

## Generation-time meta options

You can override the template defaults at generation time by passing special keys in the document's `meta` field. These options only apply to image templates; they are ignored for PDF templates.

| Key        | Type    | Description                                   | Default                |
| :--------- | :------ | :-------------------------------------------- | :--------------------- |
| `_type`    | string  | Image format: `webp`, `png`, or `jpg`         | `webp`                 |
| `_width`   | integer | Image width in pixels                         | Template setting (500) |
| `_height`  | integer | Image height in pixels                        | Template setting (500) |
| `_quality` | integer | Compression quality from 1 to 100 (WebP only) | `100`                  |

```json5 title="Request body with meta overrides"
{
  document: {
    document_template_id: "YOUR_IMAGE_TEMPLATE_ID",
    payload: { title: "Hello World" },
    status: "pending",
    meta: {
      _type: "png",
      _width: 1200,
      _height: 630,
    },
  },
}
```

> [!WARNING]
> The `_quality` option only applies to WebP images. PNG is always lossless, and JPG uses a fixed quality setting.


> [!TIP]
> For social media cards and Open Graph images, `1200x630` is the most widely recommended size. Pass `"_type": "png"` for maximum compatibility.


## Transparent backgrounds

Transparency is controlled in the **template settings**, not at generation time. Enable it when you need images without a background (useful for logos, watermarks, and overlay graphics).

Transparent backgrounds are supported by **WebP** and **PNG**. JPG does not support transparency: any transparent areas render as white.

## Custom filenames for images

The `_filename` [meta key](./custom-filename.md) works the same way for images as it does for PDFs. PDFMonkey appends the correct extension (`.webp`, `.png`, or `.jpg`) automatically:

```json
{
  "meta": {
    "_filename": "social-card-march",
    "_type": "png"
  }
}
```

This produces a file named `social-card-march.png`.

## Frequently asked questions

**What happens if I use image meta options on a PDF template?**

They are ignored. The `_type`, `_width`, `_height`, and `_quality` meta keys only affect image templates.

**Can I change the output format of an existing template?**

Yes. Open the template settings in the Dashboard and change the output type. Existing documents generated from the template are not affected; only new documents use the updated setting.

**Is there a maximum image size?**

There is no hard pixel limit, but very large images (above 4000 x 4000 px) increase generation time and memory usage. Keep dimensions reasonable for your use case.

**Do webhooks work with image generation?**

Yes. [Webhooks](./webhooks.md) fire on `documents.generation.success` and `documents.generation.failure` regardless of output type.

## Related pages

- [Generate PDFs with the API](./api-pdf-generation.md): end-to-end generation workflow
- [Set a Custom Filename](./custom-filename.md): control the filename of generated files
- [API Documents reference](../api/documents.md): full parameter documentation for `meta` and other fields
- [Document Statuses and Lifecycle](./document-statuses.md): understand the generation lifecycle
- [The Download URL](./download-url.md): how to retrieve the generated file
- [Generate Factur-X Electronic Invoices](./electronic-invoicing.md): electronic invoicing needs PDF output, not images


## FAQ

**Can PDFMonkey generate images instead of PDFs?**

Yes. PDFMonkey supports WebP, PNG, and JPG image generation alongside PDFs. Create a template with the "Image" output type, then use the same API endpoints to generate images.

**What is the default image format in PDFMonkey?**

WebP is the default format for image templates. It provides good quality at a smaller file size and supports transparent backgrounds. You can override this by passing "_type": "png" or "_type": "jpg" in the document metadata.

**How do I set the dimensions of a generated image?**

Set the default dimensions in the template settings (width and height in pixels, defaulting to 500x500). You can override these at generation time by passing "_width" and "_height" in the document metadata.
