Convert PDF to Images

Endpoint #

POST https://pixlab.davix.dev/v1/pdf

Action #

action=to-images

Description #

The Convert PDF to Images action converts selected pages from a PDF document into image files using the H2I engine (PixLab).

Each selected page is rendered as a separate image output. This allows applications to generate PDF previews, extract pages for display, convert document pages into image-based workflows, and process PDF content as individual images. The action is part of the public /v1/pdf API and returns generated files through signed output URLs under the public PDF output path.

Request Format #

Requests to /v1/pdf must use:

• Content-Type: multipart/form-data
• API key authentication in request headers
• PDF upload through the files field

For non-merge PDF actions, the route uses the first uploaded PDF file as the primary input.

Parameters #

action #

Type: string
Required: Yes
Accepted value: to-images

Specifies that the request should convert pages from a PDF into image outputs.

files #

Type: file upload (multipart/form-data)
Required: Yes

The source PDF document.

• uploaded through the files field
• must be a valid PDF upload
• for non-merge actions, the first uploaded PDF file is used as the primary input

pages #

Type: string
Required: No
Default: all

Selects which pages to convert.

Supported forms:

• all
• first
• single page such as 1
• multiple pages such as 1,3,5
• ranges such as 2-6

Notes:

• page values are parsed from CSV/range syntax
• values are clamped to the document page count

format #

Type: string
Required: No
Default: png

Specifies the output image format for action=to-images. The public examples and reference support image output such as:

• png
• jpeg
• jpg
• webp

quality #

Type: integer-like
Required: No

Controls output quality for image formats that use compression. This field is supported for to-images, with parsing and clamping handled by the action helper.

density #

Type: integer-like
Required: No

Controls PDF page rendering density when converting pages into images. This field is supported for to-images, with parsing and clamping handled by the action helper.

Supported Parameters #

The Convert PDF to Images action supports the following parameters:

Parameter	Description
action	Must be to-images
files	Source PDF upload
pages	Page selector
format	Output image format
quality	Output quality control
density	PDF render density

These are the public action-specific parameters documented for action=to-images.

Full cURL Example #

curl -sS -X POST "https://pixlab.davix.dev/v1/pdf" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Idempotency-Key: pdf-to-images-001" \
  -F "action=to-images" \
  -F "files=@/path/to/document.pdf" \
  -F "pages=1-3" \
  -F "format=png" \
  -F "quality=90" \
  -F "density=300"

This example includes the full documented public parameter surface for the Convert PDF to Images action:

• action=to-images
• source PDF upload in files
• pages
• format
• quality
• density
• optional idempotency header

The API accepts both Idempotency-Key and X-Idempotency-Key.

Success Response #

Successful /v1/pdf requests return either a single output object or a results array, depending on the action. For action=to-images, the public success pattern is a multi-output response because each selected page is returned as a separate image file. Output URLs are signed and served from the public PDF output path.

Use this conservative public example:

{
  "results": [
    {
      "url": "https://pixlab.davix.dev/pdf/page-1.png"
    },
    {
      "url": "https://pixlab.davix.dev/pdf/page-2.png"
    },
    {
      "url": "https://pixlab.davix.dev/pdf/page-3.png"
    }
  ],
  "request_id": "req_abc123"
}

Response Fields #

results[] #

Array of generated output images. One result is returned for each selected page.

url #

Signed output URL for a generated page image. URLs are returned under the public PDF output path.

request_id #

Request identifier returned by the API when available.

Errors #

The public /v1/pdf endpoint documents the following errors for PDF actions:

• missing_field
• invalid_parameter
• unsupported_media_type
• pdf_page_limit_exceeded
• rate_limit_exceeded
• rate_limit_store_unavailable
• monthly_quota_exceeded
• server_busy
• timeout
• pdf_tool_failed

The shared upload/error layer can also return:

• invalid_upload
• file_too_large
• too_many_files
• total_upload_exceeded

HTTP Status Codes #

• 400 → invalid request fields or parameters
• 413 → upload limits exceeded or PDF page limit exceeded
• 415 → unsupported media type
• 429 → rate limit or monthly quota exceeded
• 503 → timeout, rate-limit store unavailable, or server busy
• 500 → PDF processing failure

Usage Notes #

Idempotency-Key is optional and supported for retry-safe request handling.

Each selected page is returned as a separate image output.

pages can be used to convert the full document or only selected pages.

Higher density values increase rendered detail and can increase processing cost. This field is supported specifically for to-images.

Output files are returned through signed URLs. Applications that need long-term storage should store generated files externally. The platform is not intended as long-term file hosting.