Public API v1.0

Real Image Resizer API

Server-side image processing for all formats and units. Use these endpoints to resize, crop, convert, and batch-process images programmatically.

Overview

The API is served from the backend at /api. All image processing happens server-side using Sharp for decoding, scaling, and encoding. Uploaded images are held in memory, uploaded to R2, and automatically deleted the moment the user downloads the result.

Base URL: http://localhost:5000/api

Authentication

Authenticated endpoints validate the Better Auth session from the Authorization: Bearer <session-token> header or the session cookie. Requests without a valid session are rejected with 401 Unauthorized.

Authorization: Bearer <session-token>

Endpoints

Method	Endpoint	Auth	Description
GET	`/health`	No	Health check. Reports database connectivity.
GET	`/api`	No	API index with full endpoint listing.
POST	`/api/image/meta`	Yes	Upload an image file and get its width, height, format, and size.
POST	`/api/image/url-fetch`	Yes	Fetch an image from a remote URL and return it as base64 with metadata.
POST	`/api/image/resize`	Yes	Resize a single image. Supports px, %, in, cm, and mm units, format conversion, and optional targetFileSizeKB for smart quality tuning.
POST	`/api/image/resize-batch`	Yes	Upload up to 20 images as multipart `images[]` files and receive a ZIP archive of all resized outputs.
POST	`/api/image/crop`	Yes	Crop an image by pixel coordinates (x, y, width, height).
GET	`/api/image/download/:fileId`	Yes	Stream the processed file back to the client. The file is automatically purged from R2 after download.
GET	`/api/history`	Yes	List the signed-in user's resize/crop history with pagination, search, and filters.
POST	`/api/contact`	No	Submit a contact form message.
GET	`/api/admin/storage`	Yes	List files currently stored in R2.

Units & Formats

Supported Units

px — pixels
% — percent of original
in — inches (DPI-aware)
cm — centimeters (DPI-aware)
mm — millimeters (DPI-aware)

Supported Formats

jpeg / jpg
png
gif
webp
heic (decoded via HEIC → JPEG pipeline)

Errors

Errors are returned as JSON with an error field:

{ "error": "Image resizing failed" }