PDF tools

Inspect, render, merge and extract PDFs with authenticated multipart requests. Outputs are ephemeral and consume processing credits.

On this page

Operations and responses
Render and page selection
Multipart examples
Bounds and document compatibility

Operations and responses

POST path (under /v1/projects/{projectId})	Input	Success / credits
/tools/pdf/info	Multipart file	JSON: `pageCount`, encrypted, pages / 1
/tools/pdf/render	Multipart file + query options	One page: binary; multiple: JSON pages / one per page
/tools/pdf/merge	Repeated file in desired order	PDF bytes / 2
/tools/pdf/extract	Multipart file + pages or range	PDF bytes / 1

Info returns page dimensions in the success envelope. Multi-page render returns data.pages, each with pageNumber, width, height, contentType and base64 data. Single-page render returns X-Pdf-Page, X-Image-Width and X-Image-Height headers. Always check status before decoding a binary response.

Delivery noteSAMPLE-1042 · two pages

Field notebooks, packing details and a receiving checklist.

Download delivery-note.pdf

Care guideOne page

Short product care instructions for a document packet.

Download care-guide.pdf

Original synthetic PDF fixtures with no real order or personal data. Combine them in the document workflow.

Render and page selection

Field	Type / values	Contract
`pages`	string	Optional. Unique comma-separated 1-based pages in requested order, e.g. 1,3,5. Mutually exclusive with range/all. Omit selection to render page 1.
`rangeStart`	integer	Optional. Min 1. Max 100. Inclusive 1-based page number; `rangeStart` and `rangeEnd` must be provided together and cannot be combined with pages/all.
`rangeEnd`	integer	Optional. Min 1. Max 100. Inclusive 1-based page number; `rangeStart` and `rangeEnd` must be provided together and cannot be combined with pages/all.
`all`	boolean	Optional. Default: false. Render the first pages up to the configured cap (default/max 10). Mutually exclusive with pages/range; does not return pages beyond the cap.
`format`	png \| jpeg \| webp	Optional. Default: png.
`scale`	number	Optional. Default: 1. Min 0.5. Max 2.
`quality`	integer	Optional. Default: 80. Min 1. Max 100. JPEG/WebP encoder quality; PNG ignores this value.

Send selection as query parameters: pages=1,3 or a complete rangeStart/rangeEnd pair, or all=true for render only. These are mutually exclusive. Render defaults to page 1; all stops at the configured render cap. Extract requires pages or a complete range. Page numbers are 1-based, unique and within the source document. Selection strings are limited to 200 characters.

Field	Type / values	Contract
`pages`	string	Optional. Unique comma-separated 1-based pages in requested order, e.g. 1,2,5. Required unless a complete range is supplied.
`rangeStart`	integer	Optional. Min 1. Max 100. Inclusive 1-based page number; `rangeStart` and `rangeEnd` must be provided together and cannot be combined with pages/all.
`rangeEnd`	integer	Optional. Min 1. Max 100. Inclusive 1-based page number; `rangeStart` and `rangeEnd` must be provided together and cannot be combined with pages/all.

Multipart examples

Use your project key and API origin. Download the two-page delivery note as delivery-note.pdf.

cURL example

curl --fail-with-body "$IMAZEO_API_ORIGIN/v1/projects/$IMAZEO_PROJECT_ID/tools/pdf/render?pages=1&format=webp&scale=1" \
  -H "X-API-Key: $IMAZEO_API_KEY" -F "file=@delivery-note.pdf" --output page.webp

Inspect, merge and extract · cURL

curl --fail-with-body "$IMAZEO_API_ORIGIN/v1/projects/$IMAZEO_PROJECT_ID/tools/pdf/info" -H "X-API-Key: $IMAZEO_API_KEY" -F "file=@delivery-note.pdf"

curl --fail-with-body "$IMAZEO_API_ORIGIN/v1/projects/$IMAZEO_PROJECT_ID/tools/pdf/merge" -H "X-API-Key: $IMAZEO_API_KEY" -F "file=@delivery-note.pdf" -F "file=@care-guide.pdf" --output merged.pdf

curl --fail-with-body "$IMAZEO_API_ORIGIN/v1/projects/$IMAZEO_PROJECT_ID/tools/pdf/extract?pages=2" -H "X-API-Key: $IMAZEO_API_KEY" -F "file=@delivery-note.pdf" --output selected.pdf

Download care-guide.pdf above for the merge example. cURL can write JSON errors to the output path: use generated files only after a successful command. Let your HTTP client set the multipart boundary. PDF uploads do not use the image upload X-Upload-Length contract. These tool routes do not store uploaded PDFs or output media for later retrieval.

Illustrative PDF info response (first page shown)

{
  "success": true,
  "data": {
    "pageCount": 2,
    "encrypted": false,
    "pages": [
      {
        "pageNumber": 1,
        "width": 595.28,
        "height": 841.89
      }
    ]
  },
  "meta": {
    "requestId": "example-pdf-info"
  }
}

For pages=1,2, render returns a JSON envelope instead of image bytes. Each data.pages item has pageNumber, width, height, contentType and base64 data. This example checks the expected PNG type before saving each page:

Multi-page render · Node.js

import { readFile, writeFile } from 'node:fs/promises';
const { IMAZEO_API_ORIGIN, IMAZEO_PROJECT_ID, IMAZEO_API_KEY } = process.env;
const form = new FormData();
form.append('file', new Blob([await readFile('delivery-note.pdf')], { type: 'application/pdf' }), 'delivery-note.pdf');
const response = await fetch(new URL('/v1/projects/' + encodeURIComponent(IMAZEO_PROJECT_ID) + '/tools/pdf/render?pages=1,2&format=png', IMAZEO_API_ORIGIN), {
  method: 'POST', redirect: 'error', signal: AbortSignal.timeout(120_000),
  headers: { 'X-API-Key': IMAZEO_API_KEY }, body: form
});
if (!response.ok) throw new Error('Render failed: ' + response.status + ' request ' + (response.headers.get('x-request-id') ?? 'unavailable'));
const result = await response.json();
if (!result.success || !Array.isArray(result.data?.pages)) throw new Error('Unexpected render response');
for (const page of result.data.pages) {
  if (!Number.isInteger(page.pageNumber) || page.pageNumber < 1 || page.contentType !== 'image/png') throw new Error('Unexpected page');
  await writeFile('delivery-page-' + page.pageNumber + '.png', Buffer.from(page.data, 'base64'));
}

To keep a supported result in your project, use a separate artifact Save request after generation.

Bounds and document compatibility

Resource	Reviewed default (deployment can differ)
Upload	20 MiB; configuration maximum 25 MiB
Source pages	100
Render	Up to 10 pages; scale 0.5–2; edge at most 4096 px
Merge	Up to 10 files, 50 MiB combined, 200 pages
Processing	1 concurrent task, 30-second timeout

Encrypted documents are rejected. Merge/extract may not preserve forms, XFA, bookmarks or encryption. Test documents with complex features before distributing output. PDF_INVALID, PDF_ENCRYPTED, PDF_TOO_LARGE and PDF_PAGE_LIMIT_EXCEEDED are terminal input errors; TOOL_BUSY can be temporary. See error recovery.

Documentation reviewed 2026-10-03 against development backend e298ec7. Verify your deployment’s API origin and limits before integrating.