Using the API

Conversion options

Send options as a JSON object in the options part of the upload. Every option is optional. Unknown options and out-of-range values are rejected with 400 invalid_option, never silently ignored, so a typing mistake can't quietly change your output.

{
  "pages": "1-3,5",
  "dpi": 300,
  "quality": 85,
  "subsampling": "auto",
  "background": "#FFFFFF",
  "name_template": "invoice_{page_number:001}",
  "zip": true,
  "password": "only-if-the-pdf-is-protected"
}

Option	Values	Default
`pages`	Which pages to convert; see below	`"all"`
`dpi`	10 up to your plan's maximum: 150 on Free, 600 on other plans	`150`
`quality`	JPEG quality, 1 to 100	`90`
`subsampling`	`"auto"`, `"444"`, `"420"` or `"gray"`	`"auto"`
`background`	The colour behind transparent areas, as `"#RRGGBB"`	`"#FFFFFF"`
`name_template`	File names; see below	`"{original}_page_{page_number:0001}"`
`zip`	`true` also creates a ZIP of all pages	`false`
`password`	The password of a protected PDF, 1 to 1024 bytes	none

Choosing pages

Pages are numbered from 1. Duplicates are removed, and pages are always converted in ascending order.

Value	Converts
`"all"`	Every page
`"5"`	Page 5
`"1-3"`	Pages 1, 2 and 3
`"8-"`	Page 8 to the end
`"1-3,5,8-"`	Any combination, separated by commas

Bad syntax returns 400 straight away. A page beyond the end of the document can only be detected once the PDF is opened, so the job fails with invalid_page_selection.

Choosing a DPI

DPI	Good for	Credits per page	A4/Letter page size
72 to 96	Thumbnails and previews	1	about 816 × 1056 at 96 DPI
150	Most screen use (recommended)	1	about 1275 × 1650
200 to 300	Sharp text, OCR, printing	3	about 2550 × 3300 at 300 DPI
600	Print-quality archives	8	about 5100 × 6600

Quality and subsampling

Quality 90 is a good default. Higher values give sharper images and larger files.

subsampling controls colour detail. "auto" uses 4:4:4 at quality 90 or above, and 4:2:0 below that. Choose "444" to keep coloured text crisp, "420" for smaller files, or "gray" for greyscale output.

File names

name_template must include {page_number}, can be up to 200 characters, and can't contain slashes. .jpg is added for you.

Placeholder	Becomes
`{original}`	The uploaded file name without `.pdf`
`{page_number}`	The page number: `7`
`{page_number:0001}`	The page number with zero padding: `0007`

Protected PDFs

Send the password in the password option. If it's missing or wrong, the job fails with password_required or password_incorrect; submit the job again with a new Idempotency-Key. RasterNivo opens protected PDFs only with the correct password and never cracks or bypasses protection.