How it works

Keenpix turns a URL into an optimized image. There's no build step and no SDK: the query string is the API.

The request lifecycle

 Browser
   │  GET /img/https://cdn.example.com/hero.jpg?project=ID&w=1200&fmt=auto
   ▼
 Keenpix
   │ 1. Resolve the project, check the source host against the project allowlist (+ SSRF block)
   │ 2. Build a cache key from (project, url, full transform options)
   │ 3. Cache HIT?  ──yes──▶  stream bytes from disk
   │        │ no
   │        ▼
   │ 4. Fetch the original from your origin (size-capped, IP-pinned)
   │ 5. Transform with sharp: decode → geometry → effects → re-encode
   │    or optimize SVG directly when fmt=svg
   │ 6. Write the result to the disk cache, then stream it
   ▼
 Response: image/avif|webp|jpeg  (+ image/svg+xml only for fmt=svg)
           + Cache-Control: public, max-age=31536000, immutable

Every request is also written to a log that powers the analytics.

The sharp pipeline

Keenpix decodes the source once and runs a parameter-selected, safe pipeline:

1. Decode + auto-orient — honours EXIF rotation, with a pixel ceiling that guards against decompression bombs.
2. Geometry — optional crop, trim, rotate, flip/flop, resize, and extend. Resize uses the chosen fit, multiplied by dpr, and never upscales unless enlarge=1. With no w/h, the longest side is bounded so a huge original can't pin a CPU.
3. Effects — optional flatten, grayscale, tint, modulate, gamma, negate, normalize, threshold, median, blur, and sharpen.
4. Re-encode — to the negotiated fmt at the resolved quality.

Format negotiation

When fmt=auto (or fmt is omitted) Keenpix reads the browser's Accept header and serves AVIF → WebP → JPEG in order of support, and sets Vary: Accept. Use fmt=auto behind a CDN only when that CDN can cache separate variants by Accept; otherwise generate explicit fmt=avif|webp|jpeg|png URLs. A project can turn auto-format off (then fmt=auto serves JPEG); an explicit format is always honoured. That means fmt=avif never falls back to WebP; it is a fixed-format request.

SVG is not part of auto-negotiation. If the origin is SVG and the request uses fmt=auto, Keenpix rasterizes it and returns AVIF, WebP, or JPEG like any other raster request. Only explicit fmt=svg returns SVG bytes; it accepts SVG origins, optimizes them with SVGO, strips active content, and skips the raster Sharp pipeline.

Per-project defaults

Each project carries defaults applied when a request omits a parameter — default quality, auto-format, and strip-metadata — editable under Settings → Pipeline. See Self-hosting → Configuration for the instance-wide limits.