Image Transformation

Images can be transformed on-the-fly by adding query parameters to file URLs. Transformations work with both public URLs and pre-signed URLs, and results are cached at the CDN layer.

Parameters

Parameter	Description	Values
w	Maximum width (maintains aspect ratio)	Pixels, 1 – 8000
h	Maximum height (maintains aspect ratio)	Pixels, 1 – 8000
q	Image quality	1 – 100 (applies to JPEG, WebP, AVIF, HEIC)
f	Output format	auto, same, jpeg, webp, png, avif
b	Blur sigma	0 – 250

Format options:

• auto – uses content negotiation based on the Accept header (serves WebP/AVIF to browsers that support it)
• same – keeps the original format (default)

Note

w, h, and b are bounded to keep a single transformation from exhausting server memory. Values above the maximum are rejected with a 400 error rather than silently clamped, so the caller learns the limit instead of receiving an image at an unexpected size. The values shown are the defaults; self-hosted instances can tune them with the IMAGE_TRANSFORMER_MAX_DIMENSION and IMAGE_TRANSFORMER_MAX_BLUR_SIGMA environment variables on the storage service.

Usage

TypeScript

// Fetch a 100x100 WebP thumbnail
const { body } = await nhost.storage.getFile(fileId, {
  w: 100,
  h: 100,
  f: 'webp',
})
const url = URL.createObjectURL(body)

curl

# Fetch a 100x100 WebP thumbnail
curl -H "Authorization: Bearer $TOKEN" \
  --output thumbnail.webp \
  "https://local.storage.local.nhost.run/v1/files/$FILE_ID?w=100&h=100&f=webp"

Caching Behavior

Transformed images are cached at the CDN level. The first request for a specific combination of parameters generates the transformed image; subsequent requests are served from cache.

Each unique set of query parameters is treated as a separate cached resource. Keep the number of distinct parameter combinations reasonable to maximize cache hit rates. See CDN for more details.