Image Processing

Transform, resize, crop, and optimize images on-the-fly using URL parameters.

Get Transform URL

Generate a URL for a transformed image:

transform.ts

import { Stack0 } from '@stack0/sdk'
 
const stack0 = new Stack0({
  apiKey: process.env.STACK0_API_KEY!
})
 
const { url, originalUrl } = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    width: 400,
    height: 300,
    fit: 'cover',
    format: 'webp',
    quality: 80,
  },
})
 
// Use in your app
// <img src={url} alt="Transformed image" />

Resize Options

Option	Type	Description
width	number	Target width (max 4096)
height	number	Target height (max 4096)
fit	string	cover \| contain \| fill \| inside \| outside

Fit Modes

cover

Crop to fill the exact dimensions, maintaining aspect ratio. Parts of the image may be cropped.

contain

Fit within dimensions, maintaining aspect ratio. May result in letterboxing.

fill

Stretch to fill exact dimensions. May distort the image.

inside

Fit within dimensions, maintaining aspect ratio. Never upscales.

fit-modes.ts

// Cover: crop to fill (best for thumbnails)
const thumbnail = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: { width: 200, height: 200, fit: 'cover' },
})
 
// Contain: fit within bounds (best for galleries)
const gallery = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: { width: 800, height: 600, fit: 'contain' },
})

Format Conversion

Convert images to modern formats for better compression:

format-conversion.ts

// Convert to WebP (smaller file size, wide support)
const webp = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    format: 'webp',
    quality: 80,
  },
})
 
// Convert to AVIF (smallest file size, newer browsers)
const avif = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    format: 'avif',
    quality: 70,
  },
})
 
// Auto-select best format based on browser support
const auto = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    format: 'auto', // Serves AVIF/WebP/JPEG based on Accept header
  },
})

Format	Quality Range	Best For
auto	1-100	Automatic based on browser
webp	1-100	General use, good compression
avif	1-100	Best compression, modern browsers
jpeg	1-100	Universal support
png	N/A	Lossless, transparency

Cropping

cropping.ts

// Position-based cropping
const cropped = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    width: 400,
    height: 400,
    fit: 'cover',
    crop: 'center', // center | top | bottom | left | right
  },
})
 
// Smart cropping (AI-based focus detection)
const smart = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    width: 400,
    height: 400,
    fit: 'cover',
    crop: 'smart', // Uses AI to detect important areas
  },
})
 
// Manual crop coordinates
const manual = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    cropX: 100,
    cropY: 50,
    cropWidth: 500,
    cropHeight: 300,
  },
})

Effects

effects.ts

// Blur effect
const blurred = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    blur: 10, // 0.3 to 1000
  },
})
 
// Sharpen
const sharpened = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    sharpen: 50, // 0 to 100
  },
})
 
// Adjust brightness/saturation
const adjusted = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    brightness: 10, // -100 to 100
    saturation: -20, // -100 to 100
  },
})
 
// Grayscale
const grayscale = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    grayscale: true,
  },
})

Rotation & Flip

rotation.ts

// Rotate
const rotated = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    rotate: 90, // -360 to 360 degrees
  },
})
 
// Flip horizontally
const flipped = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    flop: true, // Horizontal flip
  },
})
 
// Flip vertically
const flopped = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    flip: true, // Vertical flip
  },
})

Responsive Images

Generate multiple sizes for responsive images:

responsive.ts

// Generate srcset for responsive images
const sizes = [320, 640, 1024, 1920]
 
const srcset = await Promise.all(
  sizes.map(async (width) => {
    const { url } = await stack0.cdn.getTransformUrl({
      assetId: 'asset_xxx',
      options: { width, format: 'webp' },
    })
    return `${url} ${width}w`
  })
)
 
// Use in HTML
// <img
//   src={srcset[1]}
//   srcset={srcset.join(', ')}
//   sizes="(max-width: 640px) 100vw, 50vw"
// />

Combine Transformations

combined.ts

// Combine multiple transformations
const { url } = await stack0.cdn.getTransformUrl({
  assetId: 'asset_xxx',
  options: {
    // Resize
    width: 800,
    height: 600,
    fit: 'cover',
 
    // Format
    format: 'webp',
    quality: 85,
 
    // Effects
    sharpen: 10,
    brightness: 5,
 
    // Crop position
    crop: 'smart',
  },
})

CDN & Storage CDN API Reference