PDF Rendering API for Linux

Information

PSPDFKit Processor has been deprecated and replaced by Document Engine. To start using Document Engine, refer to the migration guide. With Document Engine, you’ll have access to robust new capabilities (read the blog for more information).

Warning

The POST /render API has been deprecated, and it may be removed in a future version of PSPDFKit. To render images from a PDF, please use the build API with image as the output format.

Rendering a Document

To render a document, submit a multipart/form-data request to the POST /render API endpoint. The response depends on whether the source document contains a single page or multiple pages:

  • Responds with application/zip, which contains the rendered pages when rendering multiple pages.

  • Responds with the image data directly when rendering a single page.

Request Headers

Available headers for POST /render are outlined below.

  • Optional: Authorization — The JSON Web Token (JWT).

  • Optional: pspdfkit-pdf-password — The password required for the PDF document to be processed.

  • Optional: X-Request-Id — If this is set, the log statements associated with the HTTP request are marked with a request_id label. Logs correlated with the same request have the same request ID. This helps you determine which request triggered a specific response and what errors or warnings were emitted during the request processing. The request ID needs to be between 20 and 200 characters long.

Request Parameters

Available parameters for POST /render are outlined below.

  • "file", "url", or "generation":

    • "file" — The document be processed.

    • "url" — The URL of the document to be processed.

    • "generation" — A JSON object describing how the document should be generated. See the PDF Generation schema guide for more information.

  • Optional: "operations" — The JSON object describing the operations to be performed on the supplied document. For all available operations, see the available operations guide.

  • Optional: Attachment data for the operations — For example, the XFDF to be imported when using the applyXfdf document operation.

Request

curl -X POST http://localhost:5000/render \
  -F [email protected] \
  -F options='{
  "options": {
    "pageIndex": 0,
    "width": 1000,
    "renderAnnotations": true,
    "format": "png"
  }
}' \
  -o result.png
POST /render HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary

--customboundary
Content-Disposition: form-data; name="file"; filename="Example.pdf"


--customboundary
Content-Disposition: form-data; name="options"
Content-Type: application/json

{
  "options": {
    "pageIndex": 0,
    "width": 1000,
    "renderAnnotations": true,
    "format": "png"
  }
}
--customboundary--

Response

HTTP/1.1 200 OK
Content-Type: image/png

<image data>

Options

The following options can be used in the POST /render API:

type Options = {
	width?: number,
	height?: number,
	pageIndex?: number | Array<number> | 'all',
	renderAnnotations?: boolean,
	format?: 'png' | 'jpeg' | 'webp',
};

width/height

The width and height options control the required dimensions of the rendered image.

Either the width or height parameter is required.

If both width and height parameters are missing or were provided at the same time, an HTTP response with the status 400 will be returned:

HTTP/1.1 400 Bad Request
Content-Type: application/json

pageIndex

The optional pageIndex option sets the pages that will be rendered. The allowed values are:

  • number — Renders a single page with this page index.

  • Array<number> — Renders a list of pages with these page indexes.

  • "all" — Renders all pages in a document.

This defaults to rendering all pages if the pageIndex option is missing.

Page indexes are zero-based non-negative integers. If an invalid pageIndex is used, an HTTP response with the status 400 will be returned:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "description": "`pageIndex` must be a non-negative integer, list of non-negative integers or `all`",
    "reason": "invalid_options"
}

If using a pageIndex for a page that isn’t present in a document, an HTTP response with the status 400 will be returned:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "description": "Page index is out of bounds.",
    "reason": "no_such_page"
}

renderAnnotations

The optional renderAnnotations option controls whether or not annotations should be rendered. It defaults to true.

format

The optional format option controls the format of the rendered image. The supported values of this option are "png", "jpeg", and "webp".

If not specified, the default rendering format is resolved from the value of the Accept header. If multiple supported image MIME types are present, the rendering format is resolved in this priority order: image/webp, image/jpeg, and image/png. This defaults to image/png if the Accept header is missing or doesn’t contain any supported image MIME type.