Conversions

Create a conversion

Upload a PDF and start converting its pages to JPG images.

POST/v1/conversions

The upload is checked immediately and the job runs in the background. Follow it with the job status or a webhook, then download the results.

Part order matters. Send options before file in the multipart/form-data body. The examples on this page already do.

Headers

Authorizationstringrequired

Bearer YOUR_API_KEY. The key needs the conversions:write scope.

Idempotency-Keystringrequired

A value you choose, unique for each conversion. Repeating a request with the same key returns the same job, with no second charge. See Retries and idempotency.

Body

filefilerequired

The PDF. Your plan sets the largest file you can upload.

optionsJSON stringoptional

Conversion options, up to 16 KB. All of the fields below are optional.

pagesstringoptional

Which pages to convert, such as "1-3,5,8-". Default "all".

dpiintegeroptional

Output resolution, from 10 up to your plan's maximum. Default 150.

qualityintegeroptional

JPEG quality, 1 to 100. Default 90.

subsamplingstringoptional

"auto", "444", "420" or "gray". Default "auto".

backgroundstringoptional

The colour behind transparent areas, as "#RRGGBB". Default "#FFFFFF".

name_templatestringoptional

File names. Must include {page_number}. Default "{original}_page_{page_number:0001}".

zipbooleanoptional

true also creates a ZIP of all pages. Default false.

passwordstringoptional

The password of a protected PDF.

More detail in Conversion options.

Response

202 Accepted returns the job.

idstring

The job ID. Use it to follow the job and get the results.

statestring

queued at first. See all states.

channelstring

Where it came from: api, web or desktop.

input_filenamestring

The name of the uploaded file.

input_bytesinteger

The size of the uploaded file.

optionsobject

The options in use, with defaults filled in.

page_countinteger or null

Pages in the PDF. null until the PDF has been opened.

pages_succeededinteger

Pages converted so far.

credits_consumedinteger

Credits charged. You pay only for pages that converted.

errorobject or null

What went wrong, when something did. See job errors.

Errors

Status	Code	What to do
400	`idempotency_key_required`	Send an `Idempotency-Key` header.
400	`invalid_option`	An option is unknown or out of range. See `field`.
401	`unauthenticated`	The API key is missing, invalid, expired or revoked.
403	`insufficient_scope`	Use a key with `conversions:write`.
403	`plan_limit_exceeded`	Above your plan, such as a DPI over its maximum.
409	`idempotency_key_reused`	The key was used for a different request.
413	`file_too_large`	Above your plan's upload limit.
415	`not_a_pdf`	The file is not a PDF.
429	`too_many_active_jobs`	Wait for one of your jobs to finish.

A wrong PDF password or too few credits appear later, on the job. See Errors.

Request

PHPPythonNode.jscURL

<?php
$api = getenv('RASTERNIVO_API_URL') ?: 'https://rasternivo-api.swiftinfocorp.com/v1';

$ch = curl_init("$api/conversions");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RASTERNIVO_API_KEY'),
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => [
        'options' => json_encode(['pages' => '1-3', 'dpi' => 300, 'zip' => true]),
        'file' => new CURLFile('report.pdf', 'application/pdf'),
    ],
]);
$job = json_decode(curl_exec($ch), true);
echo $job['id'], ' ', $job['state'], "\n";

import json
import os
import uuid

import requests

API = os.environ.get("RASTERNIVO_API_URL", "https://rasternivo-api.swiftinfocorp.com/v1")

with open("report.pdf", "rb") as pdf:
    job = requests.post(
        f"{API}/conversions",
        headers={
            "Authorization": "Bearer " + os.environ["RASTERNIVO_API_KEY"],
            "Idempotency-Key": str(uuid.uuid4()),
        },
        data={"options": json.dumps({"pages": "1-3", "dpi": 300, "zip": True})},
        files={"file": ("report.pdf", pdf, "application/pdf")},
    ).json()
print(job["id"], job["state"])

// Node.js 20 or newer: no packages needed.
import { randomUUID } from "node:crypto";
import { readFile } from "node:fs/promises";

const API = process.env.RASTERNIVO_API_URL ?? "https://rasternivo-api.swiftinfocorp.com/v1";

const form = new FormData();
form.append("options", JSON.stringify({ pages: "1-3", dpi: 300, zip: true }));
form.append("file", new Blob([await readFile("report.pdf")], { type: "application/pdf" }), "report.pdf");

const res = await fetch(`${API}/conversions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RASTERNIVO_API_KEY}`,
    "Idempotency-Key": randomUUID(),
  },
  body: form,
});
const job = await res.json();
console.log(job.id, job.state);

curl -X POST "https://rasternivo-api.swiftinfocorp.com/v1/conversions" \
  -H "Authorization: Bearer $RASTERNIVO_API_KEY" \
  -H "Idempotency-Key: report-2026-11-02-001" \
  -F 'options={"pages": "1-3", "dpi": 300, "zip": true}' \
  -F "file=@report.pdf;type=application/pdf"

Response 202

{
  "id": "01a19b62-dd01-7c80-811b-74793f0a32b6",
  "state": "queued",
  "channel": "api",
  "created_at": "2026-11-02T08:31:50Z",
  "started_at": null,
  "finished_at": null,
  "input_filename": "report.pdf",
  "input_bytes": 3585,
  "options": {
    "pages": "1-3",
    "dpi": 300,
    "quality": 90,
    "subsampling": "auto",
    "background": "#FFFFFF",
    "name_template": "{original}_page_{page_number:0001}",
    "zip": true
  },
  "page_count": null,
  "pages_selected": null,
  "pages_succeeded": 0,
  "pages_failed": 0,
  "credits_reserved": 0,
  "credits_consumed": 0,
  "error": null,
  "cancel_requested": false,
  "results_expire_at": null
}