Inkspan › Guides › How to convert a PDF to images in cURL

How to convert a PDF to images in cURL

Rasterising a PDF turns a document into something you can show in a browser, feed to a vision model, or use as a thumbnail. The /v1/pdf/to-images endpoint renders every page to PNG at a resolution you choose and returns the set as a ZIP archive.

The dpi parameter is the main lever: 72–96 for web previews, 150 (the default) for general display, and 300 when the images feed OCR or a vision model that benefits from detail.

Also in: Python · Node.js

cURL example

curl -X POST https://api.inkspan.dev/v1/pdf/to-images \
  -H "X-API-Key: ink_live_..." \
  -F "file=@input.pdf" \
  -F "dpi=150" \
  --output images.zip

Request parameters

Name	Type	Required	Description
`file`	file	yes	The PDF to rasterise.
`dpi`	integer	no	Output resolution in dots per inch. Defaults to `150`.

Response

Returns a ZIP archive as a binary stream with Content-Type: application/zip and Content-Disposition: attachment; filename=images.zip. Write the response body straight to disk — do not parse it as JSON.

Things that catch people out

The response is application/zip containing page_1.png upward — not a single image, even for a one-page PDF.
File size scales roughly with the square of the DPI. Going from 150 to 300 quadruples the pixel count, so raise it deliberately.
High DPI on a long document can produce a very large archive and a slow request. Split first if you only need certain pages.
Output is always PNG. Convert to JPEG or WebP on your side if you need smaller files for web delivery.

Errors

Status	Meaning	Fix
`401`	Invalid or missing API key	Send your key in the `X-API-Key` header.
`402`	Monthly quota exceeded	The response reports used/quota. Upgrade at inkspan.dev/#pricing.
`422`	Missing or invalid parameter	Check required fields in the table above — the body names the offending field.

Failed requests do not count against your quota; only successful ones are metered.

Frequently asked questions

What DPI should I use for a vision model?

300 is the usual choice when detail matters for OCR or extraction. For thumbnails and previews, 72–96 is plenty and far cheaper.

Can I render only one page?

Not directly. Split the PDF first and rasterise the page you need.

Can I get JPEG instead?

The endpoint returns PNG. Convert after download if you need a lossy format.

Get a free API key →

Related Manipulate guides: merge PDF files · split a PDF into pages · compress a PDF · add a watermark to a PDF · fill a PDF form