Start free trial
GuidesAPI referenceTutorialsDesktop

Tutorials

Your first API call

In a few minutes you'll have a program that converts a PDF to JPG images.

1. Create a key

  1. Sign up and verify your email, if you haven't already.
  2. Open API keys in your dashboard.
  3. Give the key a label, such as My first app. The label appears in your credit log, so you can tell keys apart.
  4. Enter your password and click Create key. Copy the key now, because it's shown only once.

2. Store the key

Keep it out of your code by putting it in an environment variable. On Windows PowerShell:

$env:RASTERNIVO_API_KEY = "rn_live_your_key_here"

On Linux or macOS:

export RASTERNIVO_API_KEY="rn_live_your_key_here"

3. Convert a PDF

Put a file named report.pdf in your folder and run this. It uploads the PDF, waits for the job and saves each page. You'll need PHP 8 with the curl extension, Python 3 with pip install requests, or Node.js 20 or newer.

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

function get_json(string $url, string $key): array
{
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ["Authorization: Bearer $key"],
    ]);
    return json_decode(curl_exec($ch), true);
}

// 1. Upload. The options field must come before the file.
$ch = curl_init("$api/conversions");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $key",
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => [
        'options' => json_encode(['pages' => 'all', 'dpi' => 150, 'quality' => 90, 'zip' => true]),
        'file' => new CURLFile('report.pdf', 'application/pdf'),
    ],
]);
$job = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) !== 202) {
    exit('Upload failed: ' . $job['error']['message'] . "\n");
}

// 2. Wait until the job ends.
while (!in_array($job['state'], ['succeeded', 'failed', 'cancelled', 'expired'])) {
    sleep(2);
    $job = get_json("$api/conversions/{$job['id']}", $key);
}
if ($job['state'] !== 'succeeded') {
    exit('Conversion ' . $job['state'] . ': ' . ($job['error']['message'] ?? '') . "\n");
}

// 3. Download every page. The links need no API key and expire after 15 minutes.
$result = get_json("$api/conversions/{$job['id']}/result", $key);
foreach ($result['pages'] as $page) {
    if (!empty($page['url'])) {
        file_put_contents(basename($page['filename']), file_get_contents($page['url']));
        echo 'Saved ', $page['filename'], "\n";
    }
}
echo 'Credits used: ', $job['credits_consumed'], "\n";
import json
import os
import time
import uuid

import requests

API = os.environ.get("RASTERNIVO_API_URL", "https://rasternivo-api.swiftinfocorp.com/v1")
headers = {"Authorization": "Bearer " + os.environ["RASTERNIVO_API_KEY"]}

# 1. Upload. requests sends the options field before the file, as the API needs.
options = {"pages": "all", "dpi": 150, "quality": 90, "zip": True}
with open("report.pdf", "rb") as pdf:
    r = requests.post(
        f"{API}/conversions",
        headers={**headers, "Idempotency-Key": str(uuid.uuid4())},
        data={"options": json.dumps(options)},
        files={"file": ("report.pdf", pdf, "application/pdf")},
    )
if r.status_code != 202:
    raise SystemExit("Upload failed: " + r.json()["error"]["message"])
job = r.json()

# 2. Wait until the job ends.
while job["state"] not in ("succeeded", "failed", "cancelled", "expired"):
    time.sleep(2)
    job = requests.get(f"{API}/conversions/{job['id']}", headers=headers).json()
if job["state"] != "succeeded":
    raise SystemExit(f"Conversion {job['state']}: {job['error']}")

# 3. Download every page. The links need no API key and expire after 15 minutes.
result = requests.get(f"{API}/conversions/{job['id']}/result", headers=headers).json()
for page in result["pages"]:
    if page.get("url"):
        with open(os.path.basename(page["filename"]), "wb") as out:
            out.write(requests.get(page["url"]).content)
        print("Saved", page["filename"])
print("Credits used:", job["credits_consumed"])
// Node.js 20 or newer: no packages needed.
import { randomUUID } from "node:crypto";
import { readFile, writeFile } from "node:fs/promises";
import { basename } from "node:path";
import { setTimeout as sleep } from "node:timers/promises";

const API = process.env.RASTERNIVO_API_URL ?? "https://rasternivo-api.swiftinfocorp.com/v1";
const headers = { Authorization: `Bearer ${process.env.RASTERNIVO_API_KEY}` };
const getJson = async (path) => (await fetch(API + path, { headers })).json();

// 1. Upload. The options field must come before the file.
const form = new FormData();
form.append("options", JSON.stringify({ pages: "all", dpi: 150, quality: 90, 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: { ...headers, "Idempotency-Key": randomUUID() },
  body: form,
});
let job = await res.json();
if (res.status !== 202) throw new Error(`Upload failed: ${job.error.message}`);

// 2. Wait until the job ends.
while (!["succeeded", "failed", "cancelled", "expired"].includes(job.state)) {
  await sleep(2000);
  job = await getJson(`/conversions/${job.id}`);
}
if (job.state !== "succeeded") throw new Error(`Conversion ${job.state}: ${job.error?.message}`);

// 3. Download every page. The links need no API key and expire after 15 minutes.
const result = await getJson(`/conversions/${job.id}/result`);
for (const page of result.pages) {
  if (page.url) {
    const file = await fetch(page.url);
    await writeFile(basename(page.filename), Buffer.from(await file.arrayBuffer()));
    console.log("Saved", page.filename);
  }
}
console.log("Credits used:", job.credits_consumed);
API="https://rasternivo-api.swiftinfocorp.com/v1"

# 1. Upload. The options part must come before the file part.
curl -X POST "$API/conversions" \
  -H "Authorization: Bearer $RASTERNIVO_API_KEY" \
  -H "Idempotency-Key: report-2026-11-02-001" \
  -F 'options={"pages": "all", "dpi": 150, "quality": 90, "zip": true}' \
  -F "file=@report.pdf;type=application/pdf"

# 2. Check the job until "state" is succeeded, failed or cancelled.
curl "$API/conversions/JOB_ID" -H "Authorization: Bearer $RASTERNIVO_API_KEY"

# 3. Get the download links, then download.
curl "$API/conversions/JOB_ID/result" -H "Authorization: Bearer $RASTERNIVO_API_KEY"
curl -o report.zip "ZIP_URL_FROM_THE_RESULT"

Next