Generate Images Instead of PDFs

Last updated March 23, 2026

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:

Pro tip

You can also duplicate an existing template and change its output type to Image.

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). As long as the document_template_id points to an image template, PDFMonkey produces an image instead of a PDF.

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.

KeyTypeDescriptionDefault
_typestringImage format: webp, png, or jpgwebp
_widthintegerImage width in pixelsTemplate setting (500)
_heightintegerImage height in pixelsTemplate setting (500)
_qualityintegerCompression quality from 1 to 100 (WebP only)100
{
  "document": {
    "document_template_id": "YOUR_IMAGE_TEMPLATE_ID",
    "payload": { "title": "Hello World" },
    "status": "pending",
    "meta": {
      "_type": "png",
      "_width": 1200,
      "_height": 630
    }
  }
}
The _quality option only applies to WebP images. PNG is always lossless, and JPG uses a fixed quality setting.
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 works the same way for images as it does for PDFs. PDFMonkey appends the correct extension (.webp, .png, or .jpg) automatically:

{
  "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 fire on documents.generation.success and documents.generation.failure regardless of output type.

Frequently asked questions

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