Skip to main content

​
Image Proxy

Proxy endpoint for fetching and optimizing images with support for resizing, format conversion (WebP/AVIF), and quality adjustment.

​
Endpoint

GET /api/proxy

​
Authentication

No authentication required.

​
Query Parameters

​
url
string
required
The URL of the image to proxy and optimize. Must be a valid HTTP/HTTPS URL.
blob: URLs are not supported on the server. Use POST /api/proxy with the Blob as the request body instead.
​
w
number
default:"0"
Target width for the image in pixels. When set to 0 or omitted, the original width is preserved.The image is resized maintaining aspect ratio.
​
q
number
default:"50"
Image quality from 1 to 100.
  • 1: Lowest quality, smallest file size
  • 100: Highest quality, largest file size
Values outside this range are automatically clamped.
​
format
string
default:"webp"
Output image format:
  • webp: WebP format (default, good compression and browser support)
  • avif: AVIF format (better compression, newer format)

​
Response

​
Success Response

Status Code: 200 OK Headers:
​
Content-Type
string
MIME type of the optimized image:
  • image/webp for WebP format
  • image/avif for AVIF format
​
Content-Length
string
Size of the optimized image in bytes.
​
Cache-Control
string
Set to public, max-age=31536000, immutable for aggressive caching (1 year).
Body: Binary image data

​
Error Response

Status Code: 400 Bad Request, 404 Not Found, or 500 Internal Server Error 
{
  "error": "Missing image URL",
  "status": 400
}

​
Examples

# Basic usage
curl "https://yourdomain.com/api/proxy?url=https://example.com/image.jpg"

# With resizing and quality
curl "https://yourdomain.com/api/proxy?url=https://example.com/image.jpg&w=800&q=80&format=webp"

​
Caching

The image proxy implements a multi-level caching strategy:
  1. Server-side Cache (Redis): Optimized images are cached for 24 hours with a key based on URL and optimization parameters
  2. Request Deduplication: Concurrent requests for the same image are deduplicated to prevent redundant processing
  3. Browser Cache: Cache-Control header set to 1 year for immutable resources
  4. Timeout Protection: 20-second timeout prevents hanging requests
Changing any query parameter (url, w, q, format) creates a new cache entry, allowing multiple optimized versions of the same source image.

​
Performance Optimization Tips

<!-- Use different sizes for different viewports -->
<picture>
  <source 
    media="(max-width: 640px)" 
    srcset="/api/proxy?url=https://example.com/image.jpg&w=640&q=75&format=webp"
  >
  <source 
    media="(max-width: 1024px)" 
    srcset="/api/proxy?url=https://example.com/image.jpg&w=1024&q=75&format=webp"
  >
  <img 
    src="/api/proxy?url=https://example.com/image.jpg&w=1920&q=80&format=webp" 
    alt="Responsive image"
  >
</picture>

​
Use Cases

  • Image Optimization: Reduce bandwidth and improve page load times
  • Responsive Images: Generate multiple sizes from a single source
  • Format Modernization: Convert legacy formats to modern WebP/AVIF
  • Thumbnail Generation: Create thumbnails on-the-fly
  • CORS Bypass: Access images from domains with restrictive CORS policies
  • CDN Alternative: Cache and serve optimized images without a separate CDN
The proxy has a 20-second timeout. Very large images or slow source servers may cause timeout errors.

Build docs developers (and LLMs) love

Get started for freeTalk to us