Developer API

Resize images to exact specs, over REST

One endpoint that does what generic image APIs don't: hit an exact KB ceiling (and floor), produce exact pixel dimensions without stretching, and return the bytes — built for passport portals, exam forms, and marketplace listing specs.

Get an API key — 500 free/month Quickstart

Note: unlike the in-browser tools, the API processes images on our servers (that's what an API is). Files are processed in memory and not stored after the response.

Quickstart

Create a key at /dashboard/api-keys (it's shown once — store it safely), then:

curl -X POST https://www.resizerelay.com/api/v1/resize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F "targetValue=100" -F "targetUnit=KB" \
  -F "width=600" -F "height=600" -F "fit=cover" \
  -o photo-600.jpg

The response body is the resized image. That example returns a 600×600 JPEG under 100 KB — a job-portal photo, done.

Authentication

Send your key on every request, either as Authorization: Bearer <key> or x-api-key: <key>. Keys can be revoked any time from the dashboard; only a hash of your key is stored on our side.

POST /api/v1/resize

Send multipart/form-data with a file field, or send the raw image bytes as the body with the same parameters as query-string params.

Parameter	Type	Description
file	file	The image (multipart field). JPEG, PNG, or WebP input, max 25 MB. Alternatively send the raw image bytes as the request body with parameters in the query string.
targetValue	number	Max output file size, in the unit given by targetUnit. The engine binary-searches encoder quality to fit, reducing dimensions only when unavoidable.
targetUnit	"KB" \| "MB"	Unit for targetValue. Defaults to KB.
minBytes	number	Min output size in bytes — for compliance bands like “20–50 KB” (send 20000).
width	number	Output width in px.
height	number	Output height in px.
fit	"cover" \| "inside" \| "pad"	cover = exactly width×height via a centered, saliency-aware crop (no stretching). pad = fit the whole image inside width×height and pad the margins with padColor (never crops). inside = fit within width×height preserving aspect, never enlarged (default).
padColor	string	Background for fit=pad: a hex like #FFFFFF (default white) or "transparent" (PNG/WebP only). Ignored for other fit modes.
format	string	Output format: image/jpeg (default), image/png, or image/webp.
quality	number	Encoder quality 0–1 (default 0.92). Ignored for png.

Response: the resized image bytes with Content-Type set to the output format, plus x-request-id, x-quota-limit, x-quota-used, and x-quota-remaining headers.

Compliance endpoints

The same engine, pointed at our compliance packs — what generic image APIs don't do. Score an image against a spec, apply a spec, or pad to an exact box. All use the same Bearer auth, quota, and headers as /resize.

POST /api/v1/validate — "will this be accepted?" Scores the image against a pack slug (optional spec), or an inline requirement (width, height, maxKb[, minKb, format, background]). Returns JSON: { image, result: { passCount, total, score, perfect, checks } }.

POST /api/v1/compliance/{slug} — applies a pack's spec (exact px via saliency crop, exact-KB ceiling + floor, required format) and returns the image. Background replacement is a client-side step and isn't applied server-side.

POST /api/v1/pad — pad-to-aspect: fit inside an exact width×height box and fill the margins with padColor, never cropping.

# Score a photo against a compliance pack (no editing) — returns JSON
curl -X POST https://www.resizerelay.com/api/v1/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg" -F "pack=us-passport"

# Apply a pack spec to the image (exact px + KB + format) — returns the image
curl -X POST https://www.resizerelay.com/api/v1/compliance/amazon \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@product.jpg" -o product-amazon.jpg

# Pad to an exact box without cropping — returns the image
curl -X POST https://www.resizerelay.com/api/v1/pad \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@product.jpg" -F "width=1600" -F "height=1600" -F "padColor=#FFFFFF" \
  -o product-square.jpg

Errors

Non-2xx responses are JSON: {"error": "...", "request_id": "..."}

Status	Meaning
400	Bad input — missing file, unparseable request, or a target the engine can't reach.
401	Missing, invalid, or revoked API key.
413	Image larger than 25 MB.
429	Burst rate limit (120 requests/min per key) or the monthly quota is exhausted. Check retry-after and the x-quota-* headers.
500	Processing failed — retry, then contact support with the request id.

Limits & pricing

• Free tier: 500 resizes per month per key — no card required.
• Burst limit: 120 requests per minute per key.
• Max upload: 25 MB per image.
• Need more volume? Contact us — metered plans are rolling out.

Official SDKs

Node.js — alienbass/resizerelay-node

npm install resizerelay

const { ResizeRelay } = require("resizerelay");
const client = new ResizeRelay(process.env.RESIZERELAY_API_KEY);

await client.resizeToFile("photo.jpg", "photo-600.jpg", {
  targetKb: 100, width: 600, height: 600, fit: "cover",
});

Python — alienbass/resizerelay-python

pip install resizerelay

from resizerelay import ResizeRelay
client = ResizeRelay(os.environ["RESIZERELAY_API_KEY"])

client.resize_to_file(
    "photo.jpg", "photo-600.jpg",
    target_kb=100, width=600, height=600, fit="cover",
)