How to Automate Image Compression with an API: A Node.js & PHP Guide

Roman Klymenko — Mon, 22 Jun 2026 09:37:05 +0000

Images are still the single heaviest asset on most web pages, and one unoptimized hero shot can wreck your Largest Contentful Paint (LCP) before a line of your JavaScript even runs. The catch is that manual optimization — dragging files through a desktop tool before every deploy — simply does not scale. The moment your users start uploading their own avatars, products, or listings, compression has to happen automatically, on the server, in real time.

That is exactly what an image optimization API is for. In this guide we wire one into a real backend using the Pixozip API, with working Node.js and PHP examples, plus the async patterns you actually need in production.

1. How an Image Optimization API Works

The flow is simpler than it looks. Instead of bundling sharp, libvips, or ImageMagick into every service and fighting native build dependencies in CI, you POST the raw image bytes to a stateless HTTP endpoint and get an optimized file back.

A typical request lifecycle looks like this:

Upload — your backend sends the raw image buffer to POST /v1/shrink.
Queue — the gateway authenticates your API key, validates the payload, and enqueues a job.
Process — a horizontally-scaled worker re-encodes the image to WebP, AVIF, or JPEG XL.
Deliver — you receive metadata plus a short-lived URL to download the optimized bytes.

Because the heavy lifting runs on dedicated workers, your application servers stay light: no CPU spikes from sharp, no memory pressure, and no native modules to compile.

Concern	In-process (sharp/IM)	Optimization API
Native build deps	Required in every image	None
CPU / memory load	On your app servers	Offloaded to workers
Horizontal scaling	Manual	Built-in queue
Modern formats	Manual per-codec	`webp` / `avif` / `jxl`

2. Node.js Integration

The official @pixozip/sdk is dependency-free — it runs on native fetch and streams, so it adds almost nothing to your bundle. Install it:

npm install @pixozip/sdk

Then compress a local file and write the result to disk:

import { Pixozip } from "@pixozip/sdk";
import * as fs from "fs/promises";

const zip = new Pixozip({ apiKey: process.env.PIXOZIP_API_KEY! });

const input = await fs.readFile("original-photo.jpg");

const result = await zip.shrink(input, {
  contentType: "image/jpeg",
  output: "webp",        // "auto" | "webp" | "avif" | "jpeg" | "png" | "jxl"
  qualityTier: "balanced" // "fast" | "balanced" | "max"
});

console.log(`Saved ${Math.round((1 - (result.ratio ?? 1)) * 100)}%`);

const optimized = await result.download();
await fs.writeFile("optimized.webp", optimized);

The result object carries everything you need: jobId, outputBytes, the compression ratio, and a download() helper that fetches the final bytes from the short-lived storage URL. You can also resize on the fly:

await zip.shrink(input, {
  contentType: "image/png",
  output: "avif",
  resize: { width: 1200, fit: "inside" } // cover | contain | fill | inside | outside
});

3. PHP Integration

For Laravel, WordPress, or plain PHP backends, the pixozip/sdk Composer package mirrors the same API:

composer require pixozip/sdk

<?php
use Pixozip\Pixozip;

$zip = new Pixozip(['apiKey' => getenv('PIXOZIP_API_KEY')]);

$bytes = file_get_contents('upload.jpg');

$result = $zip->shrink($bytes, [
    'contentType' => 'image/jpeg',
    'output'      => 'webp',
    'qualityTier' => 'balanced',
]);

// $result is an array: ['jobId' => ..., 'outputBytes' => ..., 'ratio' => ...]
$optimized = $zip->download($result['downloadUrl']);
file_put_contents('optimized.webp', $optimized);

Both SDKs throw a typed error (PixozipError in Node, PixozipException in PHP) that exposes the HTTP status and the gateway body so you can branch on rate_limit_exceeded, file_too_large, and friends.

4. Raw REST — No SDK Required

Under the hood it is just one authenticated POST. The image goes in the request body as raw bytes; the options ride along in an x-options JSON header:

curl -X POST https://api.pixozip.pretzl.dev/v1/shrink \
  -H "Authorization: Bearer img_live_your_key" \
  -H "Content-Type: application/octet-stream" \
  -H 'x-options: {"output":"webp","qualityTier":"balanced"}' \
  --data-binary @photo.jpg

This portability is the whole point of an API: any language that can make an HTTP request — Go, Python, Ruby, Rust — can optimize images with no native dependencies at all.

5. Going Async at Scale

Synchronous calls are perfect for single uploads, but for batch imports or large payloads you should not hold an HTTP connection open while a worker grinds. Pass async: true and the API returns instantly with a jobId you poll:

const job = await zip.shrink(input, { contentType: "image/jpeg", async: true });

let status = job;
while (status.status === "queued" || status.status === "processing") {
  await new Promise(r => setTimeout(r, 1000));
  status = await zip.getJob(job.jobId);
}

if (status.status === "completed") {
  await fs.writeFile("out.webp", await status.download());
}

Two more endpoints make life easier: POST /v1/shrink-from-url pulls a remote image directly (no need to buffer it yourself), and POST /v1/srcset returns a full set of responsive variants in one call — ideal for feeding a <picture> element.

6. Production Best Practices

Always send an idempotencyKey. Network retries are inevitable; an idempotency key guarantees a flaky connection never bills you — or processes the same image — twice.
Use output: "auto" to let the API negotiate the best modern format per image instead of hard-coding one.
Strip metadata by default. Leave keepMetadata off unless you genuinely need EXIF/GPS — it shaves extra bytes and removes a privacy leak.
Go async for anything batch. Queue-and-poll keeps your request workers free and your timeouts sane.
Start free. Every account gets 500 optimizations per month at no cost, and an unauthenticated POST /v1/public/shrink endpoint allows 5 test compressions per IP per day — enough to prototype before you ever add a key.

Conclusion

Build-time tooling optimizes the images you ship. An API optimizes the images everyone else uploads — automatically, at scale, without dragging native codecs into your stack. With a dependency-free SDK for Node.js and PHP and a plain REST endpoint for everything else, wiring it in is a single function call.

Grab a free API key, keep your 500 monthly optimizations, and stop shipping heavy images. Start with Pixozip →

How to Build a High-Performance Image Optimization Pipeline in 5 Minutes

Roman Klymenko — Mon, 25 May 2026 14:22:09 +0000

Images make up over 60% of average web page weight. If you're serving unoptimized, raw JPEGs or PNGs to mobile clients, your site's Largest Contentful Paint (LCP) score is taking a massive hit.

In this quick guide, we’ll show you how to automate image compression using the Pixozip SDK to convert images to AVIF/WebP on the fly.

Why AVIF over traditional JPEG?

Traditional JPEG compression is linear. AVIF uses intra-frame video compression algorithms that analyze texture patterns. This allows AVIF to shrink file sizes by 70-90% compared to legacy JPEG while keeping the same visual clarity.

Step 1: Install the SDK

Install the official Node.js SDK:

npm install @pixozip/sdk

Step 2: Initialize and Compress

Import the library, supply your API key, and call the .shrink() method. It handles error catching, request formatting, and automatic retries with exponential backoff internally:

import { Pixozip } from "@pixozip/sdk";
import * as fs from "fs/promises";

const zip = new Pixozip({ apiKey: "YOUR_API_KEY" });

// Load the image file into a buffer
const imageBuffer = await fs.readFile("./hero_banner.png");

// Compress and convert to AVIF
const result = await zip.shrink(imageBuffer, {
  contentType: "image/png",
  output: "avif",           // Automatically converts png to avif
  qualityTier: "balanced",  // Targets visually lossless quality (SSIM > 0.995)
  resize: { width: 1200 }   // Scales down layout resolutions
});

// Download and write the optimized image
const optimizedBuffer = await result.download();
await fs.writeFile("./hero_banner.opt.avif", optimizedBuffer);

console.log(`Optimized! Saved ${Math.round((1 - (result.ratio ?? 1)) * 100)}% of bytes.`);
console.log(`Download URL: ${result.downloadUrl}`);

Async Operations for High Volume

If you are processing batches of images, blocking your server thread synchronously is not ideal. You can trigger an asynchronous job and receive a webhook callback when it's done:

const job = await zip.shrink(imageBuffer, {
  contentType: "image/jpeg",
  output: "webp",
  async: true // Gateway returns 202 immediately
});

console.log(`Job queued with ID: ${job.jobId}`);

Conclusion

By adding a few lines of code to your upload pipeline, you can drastically decrease bandwidth consumption, reduce AWS S3 storage bills, and improve page speed rankings.

Get a free API key with 500 free optimizations per month at pixozip.

DEV Community: Roman Klymenko

How to Automate Image Compression with an API: A Node.js & PHP Guide

1. How an Image Optimization API Works

2. Node.js Integration

3. PHP Integration

4. Raw REST — No SDK Required

5. Going Async at Scale

6. Production Best Practices

Conclusion

How to Build a High-Performance Image Optimization Pipeline in 5 Minutes

Why AVIF over traditional JPEG?

Step 1: Install the SDK

Step 2: Initialize and Compress

Async Operations for High Volume

Conclusion