img.lu Image Compression API

Compress images to modern formats (WebP & AVIF) with zero client-side processing.

The img.lu API brings the same high-quality, privacy-first compression engine used on our web app to your applications, scripts, and backend services.

No image uploads stored — images are processed in memory and discarded immediately.
Lightning fast — optimized for low latency.
Modern formats — WebP and AVIF with smart quality settings.
Simple & RESTful — one primary endpoint for all use cases.

Base URL: https://www.img.lu

Authentication

The API is currently public for development and moderate usage. For production or high-volume usage, API keys will be introduced in a future version (v1.1+). Rate limiting applies (subject to fair usage).

Main Endpoint

GET `/api/compress`

Compress an image by providing its public URL and return the optimized version directly as a binary response.

URL Pattern:

https://www.img.lu/api/compress?url={image_url}&format={webp|avif}&quality={0.3|0.6|0.8}&max_width={pixels}

Query Parameters

Parameter	Type	Default	Required	Description
`url`	string	—	Yes	Public URL of the original image (must be accessible over HTTPS)
`format`	string	`webp`	No	Output format: `webp` or `avif`
`quality`	float	`0.6`	No	Compression quality: `0.3` (extreme), `0.6` (balanced), `0.8` (high quality)
`max_width`	integer	`1600`	No	Maximum width in pixels. Height is scaled proportionally. Use `4000` for near-original resolution.
`download`	boolean	`false`	No	If `true`, adds `Content-Disposition: attachment` header with a sanitized filename

Response

Success (200 OK): The compressed image is returned directly as binary data.
Content-Type: image/webp or image/avif
X-Original-Size: Original file size in bytes
X-Compressed-Size: Compressed file size in bytes
X-Reduction: Reduction percentage (e.g. 78)

Error Responses:
400 Bad Request — Missing or invalid url
415 Unsupported Media Type — Not a supported image format
413 Payload Too Large — Image exceeds size limits (~50 MB)
502 Bad Gateway — Failed to fetch the source image
429 Too Many Requests — Rate limit exceeded

Examples

cURL

# Basic WebP compression
curl "https://www.img.lu/api/compress?url=https://example.com/photo.jpg" \
  -o compressed.webp

# AVIF with high quality and max 1600px
curl "https://www.img.lu/api/compress?url=https://example.com/photo.jpg&format=avif&quality=0.8&max_width=1600" \
  -o photo.avif

JavaScript (Fetch)

async function compressImage(imageUrl) {
  const params = new URLSearchParams({
    url: imageUrl,
    format: 'webp',
    quality: '0.6',
    max_width: '1600'
  });

  const response = await fetch(`https://www.img.lu/api/compress?${params}`);
  
  if (!response.ok) throw new Error('Compression failed');

  const blob = await response.blob();
  const compressedUrl = URL.createObjectURL(blob);

  console.log('Original size:', response.headers.get('X-Original-Size'));
  console.log('Compressed size:', response.headers.get('X-Compressed-Size'));
  
  return compressedUrl;
}

Python (requests)

import requests

response = requests.get(
    "https://www.img.lu/api/compress",
    params={
        "url": "https://example.com/image.png",
        "format": "avif",
        "quality": "0.6",
        "max_width": "1600"
    }
)

if response.status_code == 200:
    with open("optimized.avif", "wb") as f:
        f.write(response.content)
    print("Reduction:", response.headers.get("X-Reduction"), "%")

Response Headers (Metadata)

Every successful response includes useful headers:

X-Original-Size — Original file size in bytes
X-Compressed-Size — Resulting file size in bytes
X-Reduction — Savings percentage
X-Processing-Time-Ms — Time taken to compress (in milliseconds)

Supported Input Formats

JPEG / JPG
PNG
WebP
GIF (first frame only)
AVIF (input support may vary)

Rate Limits & Quotas

Generous free tier for development and personal use.
Higher limits available for production use cases (contact us for enterprise plans).
Abuse (e.g. proxying large traffic) may result in temporary blocking.

Best Practices

Cache aggressively — The same image URL with identical parameters produces deterministic output. Use CDN caching.
Use sensible max_width — Most web use cases work great with 1600 or lower.
Prefer AVIF when browser support is known (Chrome 94+, Safari 16+, Firefox 113+).
Monitor reduction via response headers to fine-tune quality settings.
Handle errors gracefully and provide fallbacks to the original image.

Error Handling

All errors return a JSON body with the following structure:

{
  "error": "Invalid or inaccessible image URL",
  "code": "INVALID_URL"
}

Roadmap (v1.1+)

API key authentication + usage dashboard
Bulk compression endpoint (POST /api/compress/batch)
Resize + crop transformations
Webhook support for asynchronous processing
Detailed analytics per API key

Support & Feedback

Have questions or feature requests? Open an issue on our GitHub or email api@img.lu.

We built this API because we believe image optimization should be fast, private, and effortless.

Happy compressing!

img.lu Team Pure client-side & server-side image compression — March 2026