Resize Relay — Node.js SDK

Official Node.js client for the Resize Relay API — resize images to exact KB file sizes and exact pixel dimensions — the specs that passport portals, government exam forms, and marketplaces actually enforce.

• Exact-size engine — binary-searches encoder quality to hit a KB ceiling (and a floor, for "20–50 KB" style bands), reducing resolution only when unavoidable.
• Exact-dimension crops — fit: "cover" produces exactly width×height with a centered, saliency-aware crop (no stretching).
• Zero dependencies — uses the global fetch in Node 18+.
• Free tier — 500 resizes/month per key. Create a key →

Install

npm install resizerelay

Quickstart

const { ResizeRelay } = require("resizerelay");
// or: import ResizeRelay from "resizerelay";

const client = new ResizeRelay(process.env.RESIZERELAY_API_KEY);

// Job-portal photo: exactly 600×600, under 100 KB
await client.resizeToFile("photo.jpg", "photo-600.jpg", {
  targetKb: 100,
  width: 600,
  height: 600,
  fit: "cover",
});

// Exam signature: 350×200 JPEG between 10 and 20 KB
const result = await client.resize("signature.png", {
  targetKb: 20,
  minKb: 10,
  width: 350,
  height: 200,
  fit: "cover",
  format: "jpeg",
});
console.log(result.contentType, result.buffer.length, "bytes");
console.log("quota:", result.quota); // { limit: 500, used: 12, remaining: 488 }

Input can be a file path, Buffer, Uint8Array, ArrayBuffer, or Blob. The result's buffer is the resized image; quota headers are parsed for you.

Options

| Option | Type | Description | | ---------- | --------------------- | ----------- | | targetKb | number | Max output size in KB. | | targetMb | number | Max output size in MB (overrides targetKb). | | minKb | number | Min output size in KB (compliance bands). | | width | number | Output width in px. | | height | number | Output height in px. | | fit | "cover" \| "inside" | cover = exact width×height via centered crop; inside = fit within, keep aspect (default). | | format | "jpeg" \| "png" \| "webp" | Output format (default jpeg). | | quality | number | Encoder quality 0–1 (default 0.92). |

Error handling

All non-2xx responses throw a ResizeRelayError with status, requestId, and (for rate limits) retryAfter:

const { ResizeRelayError } = require("resizerelay");

try {
  await client.resize("photo.jpg", { targetKb: 50 });
} catch (err) {
  if (err instanceof ResizeRelayError) {
    console.error(err.status, err.message, "request:", err.requestId);
    if (err.status === 429 && err.retryAfter) {
      // burst limit — back off err.retryAfter seconds
    }
  }
}

| Status | Meaning | | ------ | ------- | | 400 | Bad input (missing file, unreachable target). | | 401 | Missing, invalid, or revoked API key. | | 413 | Image larger than 25 MB. | | 429 | Burst rate limit (120 req/min) or monthly quota reached. |

Links

• API documentation
• Get an API key
• Resize Relay — the free in-browser tools
• Python SDK

License

MIT