Resize & Crop

Sovrium resizes stored images at request time from query parameters on the ordinary download URL. There is no separate image service, no build step, and no second copy in storage — the original is read, transformed, and cached, and it is never modified.

GET /api/buckets/photos/files/{key}?width=400&height=300&fit=cover

The same parameters work on a signed URL and on the URL a record's attachment hands you. They apply to images only: any transform parameter on a PDF or a CSV answers 400.

Resize

Give one dimension and the other follows from the aspect ratio. An integer outside 1–2500 answers 400; the ceiling exists because these transforms run synchronously on the request path and an unbounded dimension is an unbounded amount of work.

Fit Modes

fit decides what happens when the requested box and the source aspect ratio disagree.

An unrecognised value falls back to cover rather than erroring, so fit=inside silently behaves as fit=cover — those are Sharp mode names Sovrium does not expose.

Reach for cover when the layout owns the dimensions (a square avatar, a fixed card), contain when the image owns them (a logo that must not be clipped), and fill essentially never.

Crop

When fit=cover something has to be discarded. crop chooses what:

GET /api/buckets/photos/files/{key}?width=300&height=300&fit=cover&crop=entropy
GET /api/buckets/photos/files/{key}?width=300&height=300&fit=cover&crop=50,30

entropy and attention are the ones worth knowing. On a photo library where nothing is composed for your aspect ratio, a centre crop routinely decapitates a portrait; attention finds the face. entropy is the safer generic choice for product shots and screenshots, where the subject is the detailed part.

A focal point is mapped onto a three-by-three gravity grid rather than used as exact pixel coordinates, so crop=10,90 and crop=20,80 both resolve to bottom-left. Treat it as "which corner", not "which pixel". Values outside 0–100 answer 400.

crop is parsed whatever the fit mode — an invalid focal point still errors under fit=contain — but it is only applied under fit=cover.

Format Conversion

Moved to Format & Quality — output formats, Accept-header negotiation, and compression.

Quality

Moved to Format & Quality — the quality parameter and which formats honour it.

Presets

Moved to Presets & Caching — naming a transform once and requesting it by name.

Caching

Moved to Presets & Caching — the LRU cache, ETag, and Cache-Control.

Original Preservation

Moved to Presets & Caching — what transforms never touch.

Related Pages

• Format & Quality — AVIF, WebP, and compression.
• Presets & Caching — named transforms and cache behaviour.
• File Operations — the download endpoint these parameters ride on.
• Download URLs — transforms on a signed URL.
• Attachment Fields & Storage — thumbnails from a record.