Image Transformations

Overview

Clawdy supports on-the-fly image transformations. Append query parameters to any file URL to resize, crop, convert formats, apply filters, and more — no extra configuration required.

https://your-server.com/f/{fileId}?w=300&h=300&fit=cover

When no transform parameters are present, the original file is served as-is. When parameters are present, the image is processed and the transformed result is streamed back.

Transformed images are cached for 24 hours. Repeated requests for the same transformation are served from cache instantly.

Resize

Control the output dimensions.

Parameter	Description	Example
`w`	Width in pixels	`?w=300`
`h`	Height in pixels	`?h=200`
`fit`	How the image fits the target dimensions	`?w=300&h=300&fit=cover`
`dpr`	Device pixel ratio (1-8)	`?w=300&dpr=2`
`we`	Without enlargement (don't upscale)	`?w=1000&we`

Examples

Scale to width:

/f/{id}?w=400

Exact dimensions with cover crop:

/f/{id}?w=600&h=200&fit=cover

Fit Modes

Control how the image fills the target dimensions when both w and h are set.

Value	Behavior
`inside`	Fit within bounds, preserve aspect ratio (default)
`outside`	Fill at least the bounds, preserve aspect ratio
`cover`	Crop to fill the exact dimensions
`contain`	Letterbox with background color
`fill`	Stretch to fill (ignores aspect ratio)

Examples

fit=cover — crops to fill exactly:

/f/{id}?w=300&h=300&fit=cover

fit=contain — letterboxed with background:

/f/{id}?w=300&h=300&fit=contain&bg=1a1a1a

Crop

Smart Cropping

Use the a (alignment) parameter with fit=cover to control crop position.

Value	Behavior
`center`	Center of the image (default)
`top`, `bottom`, `left`, `right`	Edge alignment
`top-left`, `top-right`, `bottom-left`, `bottom-right`	Corner alignment
`attention`	Focus on the most visually interesting area
`entropy`	Focus on the area with the most detail
`focal`	Use focal point coordinates (`fpx`, `fpy`)

Examples

Attention crop — auto-focuses on the subject:

/f/{id}?w=400&h=300&fit=cover&a=attention

Focal point crop — specify where to focus (70% from left, 30% from top):

/f/{id}?w=400&h=300&fit=cover&a=focal&fpx=0.7&fpy=0.3

Rectangle Crop

Crop a specific region before resizing.

Parameter	Description
`cx`	Crop X offset (pixels or percentage)
`cy`	Crop Y offset (pixels or percentage)
`cw`	Crop width
`ch`	Crop height
`precrop`	Apply crop before resize

/f/{id}?cx=100&cy=50&cw=400&ch=400&precrop

Format Conversion

Convert the output to a different format.

Parameter	Description	Values
`output`	Output format	`jpg`, `png`, `webp`, `avif`, `gif`, `tiff`
`q`	Quality (1-100)	Default: `80`
`ll`	Lossless compression	WebP, AVIF
`il`	Interlace / progressive loading	JPEG, PNG

Examples

Convert to WebP (smaller file size):

/f/{id}?output=webp&q=75

Convert to AVIF (best compression):

/f/{id}?output=avif&q=60

Progressive JPEG:

/f/{id}?output=jpg&q=85&il

Adjustments

Parameter	Description	Range
`blur`	Gaussian blur	`0.3` - `1000`
`sharp`	Sharpen	`0.000001` - `10`
`con`	Contrast	`-100` to `100`
`gam`	Gamma correction	`1.0` - `3.0`
`mod`	Modulate (brightness, saturation, hue)	Comma-separated
`tint`	Apply color tint	Color value

Examples

Blur ?blur=10

Sharpen ?sharp=3

High contrast ?con=50

Bright + saturated ?mod=1.3,1.5,0

Filters

Parameter	Description	Values
`filt`	Apply a filter effect	`greyscale`, `sepia`, `duotone`, `negate`
`start`	Duotone start color	Default: `C83658`
`stop`	Duotone stop color	Default: `D8E74F`

Examples

Greyscale ?filt=greyscale

Sepia ?filt=sepia

Duotone ?filt=duotone&start=0A1A2F&stop=E8D5B7

Negate ?filt=negate

Shape Masks

Apply a shape mask to the image — useful for avatars and profile pictures.

Value	Shape
`circle`	Circle
`ellipse`	Ellipse
`triangle`	Triangle
`square`	Rounded square
`star`	Star
`heart`	Heart
`pentagon`	Pentagon
`hexagon`	Hexagon

Examples

circle

hexagon

star

heart

Orientation

Parameter	Description
`flip`	Mirror vertically
`flop`	Mirror horizontally
`ro`	Rotate by degrees

Examples

Rotate 90 degrees:

/f/{id}?ro=90&w=300

Mirror horizontally:

/f/{id}?flop&w=400

Common Recipes

Thumbnail

/f/{id}?w=150&h=150&fit=cover&output=webp&q=70

Profile Avatar

/f/{id}?w=128&h=128&fit=cover&mask=circle&output=webp

Hero Image (optimized)

/f/{id}?w=1200&h=630&fit=cover&output=webp&q=80

Blurred Placeholder (LQIP)

Generate a tiny blurred image for progressive loading:

/f/{id}?w=32&h=32&blur=10&output=webp&q=20

Responsive `srcset`

<img
  src="/f/{id}?w=800&output=webp"
  srcset="
    /f/{id}?w=400&output=webp 400w,
    /f/{id}?w=800&output=webp 800w,
    /f/{id}?w=1200&output=webp 1200w
  "
  sizes="(max-width: 600px) 400px, (max-width: 1024px) 800px, 1200px"
/>

Retina Display

/f/{id}?w=300&h=300&dpr=2

Color Values

Parameters that accept colors (bg, tint, start, stop) support:

Format	Example
Named colors	`black`, `white`, `red` (140 CSS colors)
3-digit hex	`CCC`
6-digit hex	`CCCCCC`
4-digit ARGB	`5CCC` (with alpha)
8-digit ARGB	`55CCCCCC` (with alpha)

Caching

Type	Cache Duration
Original files (no params)	1 hour (`max-age=3600`)
Transformed images	24 hours (`max-age=86400`)

Transformations are deterministic — the same parameters always produce the same result, so caching is safe and automatic.

Image Transformations

On this page