Skip to main content
Version: 9.x

Render pages as images

Draws the pages of a PDF as PNG or JPEG images: thumbnails, previews, social cards.

POST/forms/pdf/render
Form data
filesfile[]required

The PDFs.

archivesfile[]

ZIP files Gotenberg unpacks: each entry counts as a file uploaded under files.

downloadFromjson

URLs Gotenberg downloads first, as if you had uploaded the files. Each entry takes a url, and optionally extraHttpHeaders.

Options
pagespages

The pages to draw.

Default: all

dpiinteger

The resolution, at least 1.

Default: 150

formatstring

png or jpeg.

Default: png

qualityinteger

jpeg only, from 1 to 100. With png, it answers 400.

Default: 100

Response

The image, or a ZIP of the images when there are several.

The route also takes the headers. An error answers a status and a message: see Errors.

Render a page​

curl \
  --request POST http://localhost:3000/forms/pdf/render \
  --form files=@report.pdf \
  --form pages=1 \
  -o report_1.png

One image answers on its own, named after the PDF and the page: report_1.png. Several come back in a ZIP.

Pick the resolution and the format​

curl \
  --request POST http://localhost:3000/forms/pdf/render \
  --form files=@report.pdf \
  --form pages=1 \
  --form dpi=72 \
  --form format=jpeg \
  --form quality=80 \
  -o report_1.jpeg

dpi sets the resolution, 150 by default. At 72, a pixel stands for a point, so a Letter page gives a 612 by 792 image. quality, from 1 to 100, applies to JPEG: with png, it answers 400. A dpi under 1 answers 400.

Render every page​

Without pages, Gotenberg draws them all:

curl \
  --request POST http://localhost:3000/forms/pdf/render \
  --form files=@report.pdf \
  -o report.zip

The ZIP holds report_1.png, report_2.png and report_3.png.

Render after other stages​

render comes last in a list of stages. On its own, it answers the images only. After other stages, the ZIP holds the PDF too, next to its images:

curl \
  --request POST http://localhost:3000/forms/pdf/pipe \
  --form files=@report.pdf \
  --form 'stages=[
    { "op": "stamp-text", "text": "DRAFT", "x": 72, "y": 72, "fontSize": 24 },
    { "op": "render", "pages": "1" }
  ]' \
  -o report.zip

Fonts the PDF doesn't embed, such as the stamp's Helvetica, draw with the fonts in Gotenberg's image. A conversion renders too: preview an office document with its first page. To capture a web page rather than a PDF, take a screenshot.

In a list of stages​

The stage also runs in a list on /forms/pdf/pipe, and on the PDFs a Chromium or LibreOffice conversion makes, in its stages field:

curl \
  --request POST http://localhost:3000/forms/pdf/pipe \
  --form files=@report.pdf \
  --form 'stages=[
    { "op": "render", "pages": "1", "dpi": 72 }
  ]' \
  -o report.zip