Image Transform API#

Use Snapkit's Image Transform API to perform real-time image transformations via URL parameters. Built on the Sharp↗ library for high-performance processing and CloudFront CDN, it provides fast image delivery worldwide.

Quick Start#

Basic Usage#

Add query parameters to uploaded image URLs for real-time transformation:

GET https://{organization}-cdn.snapkit.studio
  /{project}
  /{path}
  /{filename}
  ?transform=w:800,h:600,fit:cover,flip,grayscale,dpr:2

URL Components:

• {organization}: Organization name (e.g., acme-corp)
• {project}: Project name
• {path}: Folder path
• {filename}: Image filename
• Query parameters: Transform options (w, h, fit, etc.)

Key Features#

• Real-time transformation: Instant image transformation via URL parameters
• CDN caching: Fast image delivery from CloudFront after first transformation
• Automatic optimization: Automatic format selection based on browser capabilities
• High-resolution support: Responsive image generation based on DPR (Device Pixel Ratio)

Transform Parameters Reference#

Size & Layout#

Transform & Effects#

Region & Format#

Practical Usage Examples#

Responsive Image Optimization#

High-resolution for desktop

Mobile optimization

Thumbnail generation

Advanced Transform Combinations#

Portfolio gallery

Product images

Image crop (center 50%)

Basic Transform Options#

Resize

Rotate and flip

Blur and grayscale effects

Crop specific region

Extract 50% area from center (25% offset from each edge)

Original image

Resize applied (transform=w:300,h:200,fit:cover)

Transform Effects Visualization#

Original image

Resize + High-resolution (transform=w:300,h:200,fit:cover,dpr:2.0)

Original

Grayscale conversion

Blur effect

Original

Blur applied (transform=blur:5)

Rotation effect (transform=rotation:15,w:200)

Device Pixel Ratio (DPR) Usage#

Adjust the actual image size for high-resolution display support. Calculate the actual image size by multiplying the specified size by the DPR value.

How DPR Works#

• transform=w:300,dpr:1.0 → Actual image size: 300px (300 × 1.0)
• transform=w:300,dpr:1.5 → Actual image size: 450px (300 × 1.5)
• transform=w:300,dpr:2.0 → Actual image size: 600px (300 × 2.0)

The browser still displays at the specified size (300px), but downloads a larger image for crisp rendering.

DPR 1.0 (actual 300px)

DPR 1.5 (actual 450px)

DPR 2.0 (actual 600px)

Usage Examples#

Desktop standard resolution

High-resolution Retina mobile

High quality image output

Size optimization (lower quality)

Transform Processing Order#

Image transformations are processed in the following order:

1. Extract (region extraction) - Percentage-based crop from original image
2. Resize (size adjustment) - DPR applied
3. Rotation (rotation)
4. Flip/Flop (flipping)
5. Blur (blur effect)
6. Grayscale (grayscale conversion)
7. Format (format conversion)

Complex Transform Examples#

You can combine multiple transformations:

Size adjustment + grayscale + blur

Region extraction + rotation

High-resolution display optimization

Mobile responsive images

Rotation and flip combination

Performance & Caching#

CloudFront CDN#

All transformed images are cached on CloudFront CDN for fast delivery:

• First request: Transform original image and cache
• Subsequent requests: Instant delivery from cache
• Cache duration: 1 year

Accept Header-based Optimization#

When the format parameter is auto, the optimal format is automatically selected based on the browser's Accept header:

• AVIF-supporting browsers: Convert to AVIF format
• WebP-supporting browsers: Convert to WebP format
• Standard browsers: Convert to JPEG/PNG format

System Limits & Safeguards#

Processing Limits#

• Maximum image size: 4,096 x 4,096 pixels
• Input pixel limit: 268,402,689 pixels (approximately 16K x 16K)
• Blur intensity: Maximum 20 (CPU protection)
• DPR range: 1.0-4.0

Auto Fallback System#

Automatic handling when issues occur during transformation:

1. Parameter errors: Automatically correct invalid values
2. Transform failures: Return original image
3. Memory shortage: Ensure system safety with processing limits
4. Format errors: Convert to default JPEG format

Memory Optimization#

• Cache disabled: Sharp memory cache not used
• Auto cleanup: Automatic release of Sharp library instances after processing completion
• Single processing: Concurrency limited for memory protection

Integration & Usage#

Next.js Integration (Coming Soon)#

Currently under development. Coming soon.

Stay up-to-date:

• Join our Discord Community↗
• Star and Watch our GitHub Repository↗
• Check for updates on our blog

import { Image } from "@snapkit/nextjs";
 
<Image
  src="https://{organization}-<your-org>-cdn.snapkit.studio/{project}/images/hero.jpg"
  alt="Hero"
  width={800}
  height={600}
  transforms={{
    blur: 0,
    format: "auto",
    dpr: 2.0,
  }}
/>;

Responsive Image Implementation#

const getResponsiveUrl = (src: string, width: number, mobile = false) => {
  const dpr = mobile ? 1.5 : 3.0;
  return `${src}?transform=w:${width},dpr:${dpr},fit:cover,format:auto`;
};
 
// Usage example
<picture>
  <source media="(min-width: 768px)" srcSet={getResponsiveUrl(baseUrl, 800)} />
  <img src={getResponsiveUrl(baseUrl, 400, true)} alt="Responsive" />
</picture>;

Next Steps#

• Next.js Integration Guide - Integrate with web applications using @snapkit/nextjs
• Figma Plugin Usage - Direct image optimization from design workflows
• Performance Optimization Tips - Strategies for improving website loading speed