Stop Waiting 30 Seconds for Images to Load
A Node.js API that actually makes your images load fast (shocking, we know)
🚀Your Images Are Killing Your Website
Largest Contentful Paint: 8.2s
First Input Delay: 2.1s
Your users are literally making tea while waiting
Every day you serve 5MB images to mobile users on slow connections. They leave before your hero image loads. Your conversion rates die a slow, pixelated death.
Image Optimisation That Actually Works
A Node.js API that makes your images load faster than your boss can say "why is this taking so long?"
What This Thing Actually Does
- Compresses images without making them look like they were saved in 1995 (lossy, lossless, or glossy modes)
- Converts formats to WebP, AVIF, or whatever your heart desires (goodbye ancient JPEG)
- Resizes smartly with multiple fitting options (no more squished profile pics)
- Strips EXIF data because nobody needs your camera serial number (privacy matters)
- Handles CMYK to RGB conversion (for those fancy print files)
What You Get Back
Because knowing what to expect matters.
Simple GET Response
- Direct image binary: Just the optimised image (ready to save or display)
- Proper headers: Correct content-type and size (browsers love this)
POST/Pipeline JSON Response
"status": {"code": 2, "message": "Image processed successfully"},
"originalSize": 2048000,
"processedSize": 102400,
"compressionRatio": "5.00%",
"format": "webp",
"width": 800,
"height": 600,
"downloadUrl": "https://my.endpoint.com/downloads/1234567890.webp",
"base64": "data:image/webp;base64,..."
}
Base64 included for images under 1MB
- File stats: Before and after sizes plus compression ratio (bragging rights included)
- Download URL: Direct link to optimised image (expires after 3 days)
- Base64 data: Embedded image for small files (under 1MB)
- Dimensions: Final width and height (so you know what you got)
When Things Go Wrong
Because not every image plays nicely. Here's what to expect.
Common Error Responses
- 400 - Validation Error: Missing parameters or invalid values (check your JSON)
- 401 - Invalid API Key: Wrong or missing authentication (use 'test' for demo)
- 413 - File Too Large: Image exceeds size limits (nobody needs 50MB images)
- 415 - Unsupported Format: Can't process this file type (stick to standard images)
- 422 - Processing Error: Something broke during optimisation (corrupted image maybe?)
"status": {"code": -400, "message": "Invalid parameters"},
"error": {"code": "VALIDATION_ERROR", "details": "Missing resize_width"}
}
Always check the status code first
Three Ways to Crush Your Images
Pick your poison. All roads lead to fast-loading images.
Simple GET Request
Throw an image URL at it. Get optimised image back. Perfect for quick fixes when your boss needs results yesterday.
Advanced POST Magic
Upload files or send URLs with full control over compression, resizing, and format. For when you actually know what you're doing.
Pipeline Processing
Chain multiple operations together. Resize, rotate, flip, compress - all in one go. Like Instagram filters but useful.
Every Feature You Actually Need
Built with Sharp.js because it's fast and doesn't crash your server.
Compression Levels
- Lossless (0): Perfect quality, bigger files (for when size doesn't matter)
- Lossy (1): Great quality, smaller files (the sweet spot)
- Glossy (2): Good quality, tiny files (when bandwidth is precious)
Resize Methods
- None (0): Keep original size (just optimise)
- Outer/Contain (1): Fits inside dimensions (letterboxing if needed)
- Inner/Cover (3): Fills dimensions exactly (crops to fit)
- Smart (4): AI-powered focus detection (finds faces and important bits)
Output Formats
- WebP: Best browser support, great compression (default choice)
- AVIF: Newest format, smallest files (if browsers support it)
- JPEG: Universal support (for maximum compatibility)
- PNG: When you need transparency (logos and graphics)
- GIF: For animations (yes, it still exists)
Pipeline Operations
- Resize: Multiple fit options and smart positioning (inside, cover, contain, fill, outside)
- Convert: Change formats with quality control (lossless options available)
- Rotate: Any angle with custom backgrounds (RGBA colour support)
- Flip: Horizontal or vertical mirroring (because why not)
- Metadata: Strip or keep EXIF data (privacy vs information)
- CMYK to RGB: Convert print colours to web (automatic by default)
Show Me The Code
Real curl commands you can copy and paste right now.
Simple GET Requests
Perfect for quick optimisations. Just hit the URL and get back a smaller image.
Downloads optimised image as WebP
Resizes to 800px width max, lossless compression
Advanced POST Requests
Full control over every parameter. Because sometimes you need to be precise.
-H "x-api-key: test" \
-H "Content-Type: application/json" \
-d '{
"url": "https://images.pexels.com/photos/5604369/pexels-photo-5604369.jpeg",
"resize": 1,
"resize_width": 700,
"resize_height": 500,
"convertto": "avif",
"quality": 95,
"keep_exif": 0
}'
Returns JSON with download link and stats
-H "x-api-key: test" \
-F "image=@/path/to/your/image.jpg" \
-F "resize=3" \
-F "resize_width=600" \
-F "resize_height=400" \
-F "convertto=webp" \
-F "compression=2"
Smart crop to 600x400, glossy compression
Pipeline Processing
Chain multiple operations together. Like Photoshop actions but faster.
-H "x-api-key: test" \
-H "Content-Type: application/json" \
-d '{
"url": "https://images.pexels.com/photos/5604369/pexels-photo-5604369.jpeg",
"pipeline": {
"steps": [
{"type": "resize", "width": 800, "height": 600, "fit": "cover"},
{"type": "convert", "format": "webp", "quality": 90}
]
}
}'
Resize then convert to WebP
-H "x-api-key: test" \
-H "Content-Type: application/json" \
-d '{
"url": "https://images.pexels.com/photos/5604369/pexels-photo-5604369.jpeg",
"pipeline": {
"steps": [
{"type": "metadata", "keepExif": false},
{"type": "resize", "width": 800, "height": 600, "fit": "cover", "position": "attention"},
{"type": "rotate", "angle": 90},
{"type": "flip", "horizontal": true},
{"type": "convert", "format": "avif", "quality": 80},
{"type": "compress", "level": 1}
]
}
}'
Strip EXIF, smart crop, rotate, flip, convert to AVIF
Get It Running
Five minutes from zero to hero. Your images will thank you.
Clone & Install
git clone the repo, npm install dependencies. The usual dance.
Configure .env
Set your API key, port, storage path. Defaults work fine but customise if you're fancy.
Deploy with PM2
Production ready with process management. Because servers crash at 3am.
Ready to Speed Up Your Images?
Stop losing users to slow loading times. Your website deserves better than 5MB hero images.
Test it right now
Watch a 2MB image become 50KB in seconds
Your loading times will finally make sense. Your users might even stick around.