Docs / Quick reference

Quick reference v0.2.0

Every URL parameter, format and status code on one page. A request is GET /<path-under-data-dir>?<params> and the response is the transformed file. The Request model covers signing, caching, fallbacks, errors and capacity in more detail.

Working in PHP? The official PHP library gives you typed builders for every parameter, signed URLs, responsive srcset and <picture> markup.

Request shape

GET /photos/cat.jpg?w=600&h=400&fit=cover&g=attention&f=auto&q=high&filter=sharpen:1.2

• The path selects the file. The query string describes the transforms.
• Named values are case-insensitive (g=Center = g=center).
• Most parameters have interchangeable short and long names (w = width). Sub-parameter keys are case-sensitive.
• Grouped parameters use key:value pairs joined by | — e.g. crop=w:400|h:300|g:attention.
• A file picturium can’t process is served unchanged only if its extension is in data.serve. Otherwise you get 415.

URL parameters

Size & fit

Canvas & orientation

Format & quality

Documents & video

Crop, effects & limits

Cache & delivery

Grouped parameters

crop

Set at least one of w, h, or ar. Cropping happens on the original before sizing, fitting, or padding. Out-of-bounds areas are clamped instead of rejected. Smart gravity (g=attention or g=entropy) ignores x and y. Cropping is skipped for f=pdf, f=svg, and original.

See Cropping for region sizing, gravity, offsets, smart crop, and worked examples.

filter

Combine several effects in one value: filter=brightness:1.1|contrast:1.2|blur:2.

See Filters & effects for composition order, examples, palettes, and animation behaviour.

anim · animate

Animated GIF, WebP, AVIF, HEIC, and multi-page TIFF sources keep their animation without an anim parameter. Only webp and gif outputs can remain animated. Use anim=off (or false, no, or 0) to return only the first frame. For video, anim extracts a clip: t sets the start and frames sets its length.

See Animation & video for output-format behaviour, frame selection, video clip defaults, examples, and processing costs.

watermark

Each key falls back to its [watermark] configuration value. Use watermark=false to disable it for one request. Watermarks are skipped for f=pdf, f=svg, and original; otherwise they appear on every frame and document page. dpr scales pad, scale, and size.

See Watermarking for source precedence, path safety, placement, configuration, and worked examples.

limit · limits

thumb · thumbnail

thumb=page:1,2 still works, but its p, page, and pages keys are deprecated. Use the top-level page parameter instead. It has the same syntax and takes priority when both are present.

Formats

Input

Photos

• jpeg
• png
• tiff
• webp
• gif
• heif · heic · avif
• jxl
• jp2k
• ico
• bmp

Design & vector

• psd
• svg · svgz
• eps
• ai
• cdr · cmx · cdt
• dxf

Documents

• pdf
• doc
• docx
• odt
• rtf
• ppt
• pptx
• odp
• xls
• xlsx
• ods
• csv
• + macro & template variants

Camera RAW

• raf
• rw2
• pef
• orf
• nrw
• nef
• dng
• cr2
• cr3
• crw
• arw

Video

• mp4
• webm
• mkv
• avi
• av1
• 3gp
• m4v
• flv
• mov
• mpeg
• mts
• hevc

Output

Images

• jpeg
• webp
• png
• gif
• avif
• jxl

Animated

• webp
• gif

Documents

• pdf
• svg

pdf and svg are document passthrough: the document itself is served.

• f=auto picks the first entry of output.format_priority the client accepts, falling back to webp. gif is not in the default priority, so auto never picks it.
• Only webp and gif output can hold an animation; every other format gets the first frame.
• f=svg needs an SVG or vector source; f=pdf needs a PDF, office, SVG or vector source — otherwise 415. See Documents & vectors for page selection and conversion details.

See Output format & quality for negotiation, quality curves, encoder options, metadata, limits, and download behaviour.

HTTP status codes

Response headers to check

• Content-Type — the negotiated output MIME.
• Content-Disposition — set when download= is given.
• Cache-Control — from cache.cache_control, or no-store when force=true.
• ETag / Last-Modified — validators for conditional requests (drive the 304).
• Vary: Accept — only when the format was negotiated (f=auto).

See HTTP caching for validator precedence and the difference between cache= and force=true.

GET /health returns JSON with a status (healthy / warning / unhealthy). Worker and queue counts and memory statistics are only added with a valid security.health_token. Thresholds and HTTP behaviour are in Health & capacity.

Configuration

• File config.toml (or the path in PICTURIUM_CONFIG). Every key is optional; an unknown key refuses to boot.
• Any key can be an env var: PICTURIUM__SECTION__KEY, __ between levels, list values comma-separated. E.g. PICTURIUM__SERVER__PORT=8080.

# config.toml with every default below. Copy only the keys you change.
[server]
host = "0.0.0.0"
port = 20045
workers = 0               # 0 = 2× CPUs
queue_size = 100
log_level = "debug"

[security]
signature_enabled = false
signature_secret = ""

[cors]
allowed_origins = ["*"]   # permissive

[data]
dir = "data"              # stripped from the URL
serve = []                # ["*"] serves any file as-is

[cache]
dir = "cache"             # one process per dir
cache_control = "public, max-age=604800, must-revalidate"

[cache.memory]
limit = 256               # MiB

[cache.disk]
limit = 1024              # MiB

[image]
fit = "cover"
gravity = "center"
upsize = false
auto_rotate = true
resample = "lanczos3"
extend = "bg"

[output]
quality = "medium"
format_priority = ["jxl", "avif", "webp", "jpeg", "png"]
metadata = ["none"]
max_width = 5000          # 0 = unlimited
max_height = 5000         # 0 = unlimited
max_size = "0"            # 0 = unlimited

[watermark]
enabled = false

[video]
default_time = "1"

[svg]
allow_local_resources = false

See the config key reference for every key and its explanation. The repository also includes config.toml.example with the same defaults and inline comments.