Image Processing

PicFast offers two layers of image processing. Choose based on whether you need to transform a single image on demand or apply a fixed policy to every upload:

On-the-fly — append @ + params to any image URL; processed on the CDN/browser cache layer. Good for one-off resizes or a gallery that serves the same source at multiple sizes.
Upload-time — the server transforms and stores the result at upload time. Good for consistent compression, metadata stripping, and watermarking before storage hits the network.

On-the-fly (URL parameters)

Append @ followed by comma-separated parameters to an image URL. The result is cached and served on subsequent requests.

Quick examples

# Original
https://picfast.example.com/i/abc123.jpg

# Resize to width 300px
https://picfast.example.com/i/abc123.jpg@w_300

# Resize to height 200px
https://picfast.example.com/i/abc123.jpg@h_200

# Fit within 300×200 box (keeps aspect ratio)
https://picfast.example.com/i/abc123.jpg@w_300,h_200

# Compress to quality 80
https://picfast.example.com/i/abc123.jpg@q_80

# Convert to WebP
https://picfast.example.com/i/abc123.jpg@f_webp

# Combine all
https://picfast.example.com/i/abc123.jpg@w_300,h_200,q_60,f_webp

Parameters

Param	Description	Range
`w_`	Target width (px)	1 – 10000
`h_`	Target height (px)	1 – 10000
`q_`	Output quality	1 – 100
`f_`	Output format	`jpeg`, `png`, `webp`, `gif`

Behavior

When both w_ and h_ are set, the image is scaled to fit within the box while preserving aspect ratio (no crop).
GIF images are not processed and returned as-is.
If processing fails for any reason, the original image is returned unchanged.
Processed responses use Cache-Control: public, max-age=2592000 (30 days). CDN or browser caches will serve the processed version without hitting PicFast again.

Upload-time (server-side)

When a user uploads an image, the server applies the configured processing pipeline before storing the result. The original is discarded; only the processed version is kept.

User settings

Each user can configure their own pipeline from the gear icon on the upload page. Settings persist on the server and apply to all subsequent uploads.

Setting	Description	Default
Compression quality	JPEG/WebP quality, 1 – 100. Only applies when format is `jpeg` or `webp`.	`85`
Output format	`origin` keeps the source format; `jpeg` / `png` / `webp` transcodes.	`origin`
Strip EXIF	Removes all EXIF metadata (camera info, GPS, etc.) before storage. Recommended for privacy.	on
Text watermark	Overlays configurable text on every uploaded image. See watermark options below.	off

Watermark options

Option	Description
Text	The literal string to render. Required when watermark is enabled.
Position	`top-left`, `top-right`, `center`, `bottom-left`, `bottom-right`.
Font size	8 – 200 (CSS px).
Color	Any CSS color value (e.g. `#FFFFFF`, `oklch(...)`).
Opacity	0 – 1.

Admin controls

Admins configure two global switches on the Access settings page that override per-user settings:

Switch	Effect
`allow_user_image_processing`	When off, every user is forced to the system default pipeline (quality 85, origin format, EXIF strip on, no watermark). The user gear icon still opens the dialog but the fields are disabled.
`skip_image_processing`	When on, all uploads bypass the processing pipeline entirely. The original file is stored as-is. Useful for raw backups or trusted internal users.

Precedence: skip_image_processing wins over user settings; otherwise the user pipeline runs, falling back to system defaults if the user has not configured anything.

Behavior

Processing happens once, at upload, on the server (libvips). Network bandwidth to storage is reduced because only the processed file is uploaded.
Originals are not retained. If a user wants the unprocessed source they must keep their own copy.
Each setting has server-side validation (quality 1-100, format enum, font size 8-200, opacity 0-1). Invalid values are rejected on save with a 400.
If processing fails for any reason, the upload still succeeds with the original file stored (graceful fallback).

Backend support

Backend	On-the-fly	Upload-time	Notes
Local	Built-in	Built-in	Works out of the box
WebDAV	Built-in	Built-in	Works out of the box
S3 / OSS / COS / Kodo	Requires `link_mode: "proxy"`	Built-in	See Storage Backends for the on-the-fly requirement

For cloud backends that return direct CDN URLs, you can alternatively use the cloud provider's native image processing parameters (e.g. Alibaba OSS ?x-oss-process=..., Qiniu ?imageView2/...) in place of PicFast's on-the-fly layer.