PDF rendering server

To render pages in a document, post a multipart request to the [/api/build API endpoint][], including the desired page index or indexes in the instructions.output.pages field. To learn more about the schema for /build instructions, go to the API Reference.

In the /api/build request, set the instructions.output.type parameter to image. By default, the output.type for /build instructions is set to pdf. The page index is provided via the instructions.output.pages field, and the rendered dimensions are provided via a width, height, or dpi option.

To learn more about available options for rendering, go to the API Reference.

The format of the rendered image can be controlled via the format option. Supported image formats are PNG, JPEG, WebP, and TIFF.

• Ensure Document Engine is up and running.
• Send a multipart POST request(opens in a new tab) with instructions to Document Engine’s /api/build endpoint.

For more information, refer to the API reference to learn about the /api/build endpoint and all the actions you can perform on PDFs with Document Engine.

For an overview of multipart requests, refer to the brief tour of multipart requests blog post.

Rendering a page of a file on disk

You can render a single page or multiple pages of a document.

Rendering a single page

The following example renders the second page (with index 1) of a document. The response to this request is a PNG image file:

curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F document=@/path/to/example-document.pdf \
  -F instructions='{
  "parts": [
    {
      "file": "document"
    }
  ],
  "output": {
    "type": "image",
    "format": "png",
    "pages": {
      "start": 1,
      "end": 1
    }
  }
}' \
  -o output-image.png

POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

--customboundary
Content-Disposition: form-data; name="document"; filename="example-document.pdf"
Content-Type: application/pdf

<PDF data>
--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "output": {
    "type": "image",
    "format": "png",
    "pages": {
      "start": 1,
      "end": 1
    }
  }
}
--customboundary--

Rendering multiple pages

The following example renders the first, second, and third page (indexes 0, 1 and 2) of a document. The response to this request is a ZIP file containing all the images:

curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F document=@/path/to/example-document.pdf \
  -F instructions='{
  "parts": [
    {
      "file": "document"
    }
  ],
  "output": {
    "type": "image",
    "format": "png",
    "pages": {
      "start": 0,
      "end": 2
    }
  }
}' \
  -o result.zip

POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

--customboundary
Content-Disposition: form-data; name="document"; filename="example-document.pdf"
Content-Type: application/pdf

<PDF data>
--customboundary
Content-Disposition: form-data; name="instructions"
Content-Type: application/json

{
  "parts": [
    {
      "file": "document"
    }
  ],
  "output": {
    "type": "image",
    "format": "png",
    "pages": {
      "start": 0,
      "end": 2
    }
  }
}
--customboundary--

Rendering a page of a file from a URL

You can specify the document to render by providing a URL to the document instead of a path to the file:

curl -X POST http://localhost:5000/api/build \
  -H "Authorization: Token token=<API token>" \
  -F instructions='{
  "parts": [
    {
      "file": {
        "url": "https://pspdfkit.com/downloads/examples/paper.pdf"
      }
    }
  ],
  "output": {
    "type": "image",
    "format": "png",
    "pages": {
      "start": 1,
      "end": 1
    }
  }
}' \
  -o output-image.png

POST /api/build HTTP/1.1
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token=<API token>

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

{
  "parts": [
    {
      "file": {
        "url": "https://pspdfkit.com/downloads/examples/paper.pdf"
      }
    }
  ],
  "output": {
    "type": "image",
    "format": "png",
    "pages": {
      "start": 1,
      "end": 1
    }
  }
}
--customboundary--

Print-production rendering fidelity

Document Engine 1.18 and later supports per-request rendering options for print-production workflows:

• overprint_preview simulates CMYK overprinting for full-page REST rendering requests.
• black_rendering controls whether 100 percent K-only CMYK black is rendered as pure black for full-page REST rendering requests.
• Tile rendering requests use the corresponding overprint and pureblack path segments.
• Batch print-render requests use the corresponding JSON fields.

Document Engine doesn’t enable overprint simulation by default. When these options are omitted, overprint simulation is disabled, and 100 percent K-only black renders through regular CMYK conversion as dark charcoal, matching Acrobat.