Image DPI 1 API: Pricing, Documentation

Authentication

All requests require an API key passed via header.

Pricing: Billed at $0.002 per image — a flat rate per call. The DPI you ask for, the print size and the pixel dimensions of the source make no difference to the price.

Retries: this is an asynchronous job on shared encoding capacity, so a request can occasionally come back processing_failed or take much longer than usual. These are transient and succeed on a retry, and a failed job is never charged — the wallet hold is released. If you chain these tools, retry a failed step rather than failing the whole pipeline.

Webhook (Optional)

Add the X-Webhook-URL header to your generate request to receive a POST callback instead of polling.

X-Webhook-URL: https://your-server.com/webhook/callback

Request Parameters - Image DPI & Print Prep generate request

Native mode — re-tag only. Send just image_url and dpi and the image is re-tagged at its own pixel size, pixels untouched. A PNG source keeps its format through a metadata-only chunk copy that never re-encodes, so it comes back bit-for-bit identical apart from its density header; a JPEG source comes back a JPG. Every other case produces TIFF unless you pass format — a native-mode source that is neither PNG nor JPEG, and every resample-mode request. Pass format to pin the output type either way.

Resample mode. Add a size, or an explicit width_in + height_in, and the image is resampled to that exact physical size at your dpi. The fit is cover-cropped, so the print is filled edge to edge and the overhanging side is trimmed rather than letterboxed. Alpha is flattened onto white, and EXIF — including GPS coordinates — is stripped. A TIFF output keeps its ICC profile; a PNG output does not.

It will not quietly upscale for you. If the source has too few pixels for the print you asked for, the API answers 422 and tells you the numbers — the pixel size it has and the pixel size the job needs — rather than stretching a small file into a soft print. Send allow_upsample: true if you want it to go ahead anyway.

Ceilings. The output area is capped at 24 megapixels, roughly 12×18 in at 300 DPI; a request over that is refused as a 400 before any charge, so probing the limit is free. Source images above 120 megapixels are refused, and the job comes back FAILED with code invalid_input. The single exception is the zero-decode path, which is PNG only: a native-mode re-tag that keeps a PNG at its own pixel size and returns PNG is a metadata chunk copy, so it works at any source size. Anything else — a JPEG, TIFF or WebP source, or a PNG you asked to convert or resample — is handed to ImageMagick, which allocates per source pixel, and is subject to the same 120 MP limit. A second ceiling applies to what the pipeline renders: above 80 megapixels of output the job is refused as well, which in practice you only meet in native mode on a very large non-PNG source.

Request Headers

Response Handling

Common status codes.

Error Responses

Queue system errors and model validation errors.

Queue System Errors

// 402 — Insufficient balance
{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}

// 400 — Model not found
{
  "error": "Model not found",
  "message": "Model 'media-image-dpi' not found or is disabled"
}

// 400 — a parameter is outside its allowed range.
// Settled at the gateway from your parameters alone, BEFORE any wallet hold,
// so probing the limits costs nothing.
{
  "error": "Invalid request parameters",
  "message": "'dpi' must be <= 1200 (got 5000)",
  "violations": ["'dpi' must be <= 1200 (got 5000)"]
}

Error via Status/Webhook

{
  "request_id": "media-image-dpi_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "media-image-dpi",
  "error": "Description of the error",
  "output": null
}

Print Verdicts

Three refusals are decided after the image has been fetched and its header read, so they are not submit-time errors: the submit returns 202 as usual and the verdict arrives on the polled status response as a FAILED job. The error string carries the code invalid_input followed by our sentence for that verdict, with the numbers for your image in it.

// GET /v2/requests/status/{request_id}
// Source has too few pixels for the print, and allow_upsample was not set
{
  "request_id": "media-image-dpi_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "FAILED",
  "model_id": "media-image-dpi",
  "error": "invalid_input: The source is 1200x1600 px, which is only 150 DPI at 8x10 in — printing that size at 300 DPI needs 2400x3000 pixels. Upscale the image first, ask for a smaller physical size, or send allow_upsample: true to accept a softer print.",
  "output": null
}

The numbers in each sentence are computed for your image, so treat the examples above as shapes rather than fixed strings — match on the invalid_input code, not on the wording.

Retrieving Results

Poll the universal status endpoint to check progress and retrieve results.

Endpoint

GET https://gateway.pixazo.ai/v2/requests/status/{request_id}
Ocp-Apim-Subscription-Key: YOUR_API_KEY

curl -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  "https://gateway.pixazo.ai/v2/requests/status/media-image-dpi_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

{
  "request_id": "media-image-dpi_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "media-image-dpi",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/media-image-dpi_019dxxxx/output.tiff"
    ],
    "media_type": "image/tiff"
  },
  "created_at": "2026-03-31T10:00:00.000Z",
  "updated_at": "2026-03-31T10:00:15.000Z",
  "completed_at": "2026-03-31T10:00:15.000Z"
}

Response Fields

Status Values

Status Flow

QUEUED → PROCESSING → COMPLETED
                    → FAILED
                    → ERROR

Typical Workflow

1. Send a generate request to the API endpoint
2. Save the request_id from the response
3. Poll every 5-10 seconds: GET /v2/requests/status/{request_id}
4. When status is "COMPLETED", download from output.media_url

Tip: Use X-Webhook-URL header to get a callback instead of polling.