\n\n| \n\n width / w
\n/w_160/sample.jpg\n
\nPositive integer. (docs)\n | \n\n\n height / h
\n/h_120/sample.jpg\n
\nPositive integer. (docs)\n | \n
\n\n| \n\n resize / s
\n/s_200x200/sample.jpg\n
\n{width}x{height} of positive integers. A single value (s_200) is a square. (docs)\n | \n\n\n kernel
\n/s_80x80,kernel_nearest/sample.jpg\n
\nSets kernel option for resize. One of nearest, linear, cubic, mitchell, lanczos2, lanczos3 (default), mks2013 or mks2021. (docs)\n | \n
\n\n| \n\n fit
\n/s_200x200,fit_contain,b_00ff00/sample.jpg\n
\nSets fit option for resize. One of contain, cover (default), fill, inside or outside. (docs)\n | \n\n\n position / pos
\n/s_200x200,pos_top/sample.jpg\n
\nSets position option for resize. A position (top, right top, right, right bottom, bottom, left bottom, left, left top), gravity (north, northeast, ..., center) or strategy (entropy, attention). Since _ separates arguments, multi-word values use - (pos_right-top). The numeric gravity (0-8) and strategy (16-17) constants are also accepted. (docs)\n | \n
\n\n| \n\n extend
\n/extend_20_40_20_40_mirror/sample.jpg\n
\nExtend / pad / extrude one or more edges of the image. Format: extend_{top}_{right}_{bottom}_{left}_{extendWith}. Edges are integers between 0 and 10000. Optional extendWith: background (default), copy, repeat or mirror. When extending with background, the colour comes from the background / b modifier, e.g. b_00ff00,extend_20_40_20_40. (docs)\n | \n\n\n background / b
\n/rotate_45,b_00ff00/sample.jpg\n
\nBackground colour used by extend, rotate, flatten, opacity and resize (with fit_contain).\n | \n
\n\n| \n\n extract / crop
\n/extract_60_20_180_140/sample.jpg\n
\nExtract/crop a region of the image, as extract_{left}_{top}_{width}_{height}. All four arguments are required; width and height must be positive. (docs)\n | \n\n\n format / f
\n/f_webp/sample.jpg\n
\nSupported formats: jpg, jpeg, png, webp, avif, gif, heif, tiff and auto (experimental, only with middleware). (docs)\n | \n
\n\n| \n\n quality / q
\n/q_10/sample.jpg\n
\nInteger between 1 and 100.\n | \n\n\n rotate
\n/rotate_45/sample.jpg\n
\nAngle in degrees, between -3600 and 3600. Angles that are not a multiple of 90 are filled with the background / b colour. Without an angle (rotate) the image is auto-oriented from its EXIF tag. (docs)\n | \n
\n\n| \n\n enlarge
\n/enlarge,s_400x400/sample.jpg\n
\nAllow the image to be upscaled. By default the returned image will never be larger than the source in any dimension, while preserving the requested aspect ratio.\n | \n\n\n flip
\n/flip/sample.jpg\n
\nMirror the image vertically. (docs)\n | \n
\n\n| \n\n flop
\n/flop/sample.jpg\n
\nMirror the image horizontally. (docs)\n | \n\n\n sharpen
\n/sharpen_5/sample.jpg\n
\n{sigma}_{flat}_{jagged}_{x1}_{y2}_{y3}. sigma is between 0.000001 and 10, the rest between 0 and 1000000. Without arguments (sharpen) a mild sharpen is applied. (docs)\n | \n
\n\n| \n\n median
\n/median_10/sample.jpg\n
\nSquare mask size, an integer between 1 and 1000 (defaults to 3). (docs)\n | \n\n\n blur
\n/blur_5/sample.jpg\n
\n{sigma}_{precision}_{minAmplitude}. sigma is a number between 0.3 and 1000, precision one of integer (default), float or approximate, minAmplitude a number between 0.001 and 1. Without arguments (blur) a mild blur is applied. (docs)\n | \n
\n\n| \n\n dilate
\n/dilate_5/sample-logo.png\n
\nExpand foreground objects. Width in pixels, an integer between 1 and 100 (defaults to 1). Capped below the sharp maximum, since the cost grows with the width. (docs)\n | \n\n\n erode
\n/erode_5/sample-logo.png\n
\nShrink foreground objects. Width in pixels, an integer between 1 and 100 (defaults to 1). Capped below the sharp maximum, since the cost grows with the width. (docs)\n | \n
\n\n| \n\n clahe
\n/clahe_20_20_5/sample.jpg\n
\nContrast limiting adaptive histogram equalization, as {width}_{height}_{maxSlope}. width is required and height defaults to it (a square window); both are integers between 1 and 100, capped below the sharp maximum since the cost grows with the window, and clamped to the source dimensions. maxSlope is an integer between 0 and 100 (defaults to 3). (docs)\n | \n\n\n flatten
\n/flatten,b_00ff00,f_jpeg/sample-alpha.png\n
\nRemove alpha channel, if any, and replace with the background / b colour. (docs)\n | \n
\n\n| \n\n unflatten
\n/unflatten,f_webp/sample-logo.png\n
\nMake every fully white pixel transparent, so the output format needs an alpha channel (png, webp, avif). (docs)\n | \n\n\n gamma
\n/gamma_3/sample.jpg\n
\n{gamma}_{gammaOut}, each a number between 1.0 and 3.0 (defaults to 2.2). (docs)\n | \n
\n\n| \n\n negate
\n/negate/sample.jpg\n
\nOptional {alpha} (true by default) controls whether the alpha channel is negated too, e.g. negate_false. (docs)\n | \n\n\n normalize
\n/normalize_10_90/sample.jpg\n
\nStretch the luminance to the full dynamic range, as {lower}_{upper} percentiles. lower is a number between 0 and 99 (defaults to 1), upper between 1 and 100 (defaults to 99) and has to be greater than lower. (docs)\n | \n
\n\n| \n\n threshold
\n/threshold_128/sample.jpg\n
\n{threshold}_{grayscale}. threshold is an integer between 0 and 255 (defaults to 128). Optional grayscale (true by default) converts to single channel grayscale first, e.g. threshold_128_false. (docs)\n | \n\n\n linear
\n/linear_1.5_-30/sample.jpg\n
\nLevels adjustment applying a * input + b, as {a}_{b}. a is the multiplier (defaults to 1), b the offset (defaults to 0). (docs)\n | \n
\n\n| \n\n tint
\n/tint_00ff00/sample.jpg\n
\nTint colour. (docs)\n | \n\n\n grayscale
\n/grayscale/sample.jpg\n
\nConvert to 8-bit greyscale. (docs)\n | \n
\n\n| \n\n modulate
\n/modulate_1.5_2_90_10/sample.jpg\n
\nTransforms the image using {brightness}_{saturation}_{hue}_{lightness}. brightness and saturation are numbers >= 0, hue is an integer in degrees. Each is also available on its own (below), which is easier to read when only one is needed. (docs)\n | \n\n\n brightness
\n/brightness_1.5/sample.jpg\n
\nBrightness multiplier, a number >= 0. Required. (docs)\n | \n
\n\n| \n\n saturation
\n/saturation_0.3/sample.jpg\n
\nSaturation multiplier, a number >= 0. Required. (docs)\n | \n\n\n hue
\n/hue_90/sample.jpg\n
\nHue rotation, an integer in degrees. Required. (docs)\n | \n
\n\n| \n\n lightness
\n/lightness_30/sample.jpg\n
\nLightness addend, a number. Required. (docs)\n | \n\n\n opacity
\n/opacity_0.5,f_webp/sample.jpg\n
\nOpacity, a number between 0 and 1. Required. The image is made transparent, so the output format needs an alpha channel (png, webp, avif). Set the background / b colour to blend into it instead and keep the output opaque, e.g. opacity_0.5,b_fff,f_jpeg.\n | \n
\n\n| \n\n animated / a
\n/a,w_160/sample.gif\n
\nProcess every frame of an animated image. Experimental.\n | \n\n No sample: the sample source has no uniform border to trim. \ntrim
\n/trim_30/sample.jpg\n
\nTrim pixels from the edges that are within the threshold of the top-left pixel colour. Threshold is a number >= 0 (defaults to 10). (docs)\n | \n
\n\n| \n No sample: the sample source carries no EXIF Orientation tag. \nautoorient
\n/autoorient/sample.jpg\n
\nRotate and flip the image based on its EXIF Orientation tag, then remove the tag. (docs)\n | \n | \n
\n
\n\n\n\n## Programmatic API\n\nCreate an IPX instance with `createIPX()`, then either serve it directly or mount it as a handler in your own app.\n\n**Example:** Using built-in server\n\n\n\n```ts [serve.ts]\nimport { serveIPX, createIPX, ipxFSStorage, ipxHttpStorage } from \"ipx\";\n\nconst ipx = createIPX({\n storage: ipxFSStorage({ dir: \"./public\" }),\n httpStorage: ipxHttpStorage({ domains: [\"picsum.photos\"] }),\n alias: { \"/picsum\": \"https://picsum.photos\" },\n});\n\n// http://localhost:3000/w_512/picsum/1000\nserveIPX(ipx);\n```\n\n\n\n**Example**: Using with [h3](https://h3.dev)\n\n\n\n```ts [h3.ts]\nimport { H3, serve } from \"h3\";\n\nimport {\n createIPX,\n ipxFSStorage,\n ipxHttpStorage,\n createIPXFetchHandler,\n} from \"ipx\";\n\nconst ipx = createIPX({\n storage: ipxFSStorage({ dir: \"./public\" }),\n httpStorage: ipxHttpStorage({ domains: [\"picsum.photos\"] }),\n alias: { \"/picsum\": \"https://picsum.photos\" },\n});\n\nconst app = new H3();\n\napp.mount(\"/ipx\", createIPXFetchHandler(ipx));\n\n// http://localhost:3000/ipx/w_512/picsum/1000\nserve(app);\n```\n\n\n\n**Example:** Using with [express](https://expressjs.com)\n\n\n\n```ts [express.ts]\nimport Express from \"express\";\n\nimport {\n createIPX,\n ipxFSStorage,\n ipxHttpStorage,\n createIPXNodeHandler,\n} from \"ipx\";\n\nimport type { RequestHandler } from \"express\";\n\nconst ipx = createIPX({\n storage: ipxFSStorage({ dir: \"./public\" }),\n httpStorage: ipxHttpStorage({ domains: [\"picsum.photos\"] }),\n alias: { \"/picsum\": \"https://picsum.photos\" },\n});\n\nconst app = Express();\n\napp.use(\"/ipx\", createIPXNodeHandler(ipx) as RequestHandler);\n\n// http://localhost:3000/ipx/w_512/picsum/1000\napp.listen(3000, () => {\n console.log(\"Server is running on http://localhost:3000\");\n});\n```\n\n\n\n## Config\n\nEvery option can also be set universally with an `IPX_*` environment variable, which is how the CLI is configured. Explicit options win over the environment.\n\n### General\n\n| Option | Environment variable | Default | Description |\n| -------------------- | -------------------------- | ------- | --------------------------------------------------------- |\n| `alias` | `IPX_ALIAS` | `{}` | Map URL prefixes to other prefixes or remote origins. |\n| `maxOutputDimension` | `IPX_MAX_OUTPUT_DIMENSION` | `8192` | Maximum width and height (in pixels) of the output image. |\n\nRequested `width`, `height` and `resize` dimensions are clamped to `maxOutputDimension`, preserving the requested aspect ratio, and `extend` edges are clamped so the extended canvas stays within it. This bounds how much memory a single request can allocate: sharp only limits the _input_ size, so without it `/enlarge,s_20000x20000/image.jpg` (or `/extend_10000_10000_10000_10000/image.jpg`) allocates gigabytes from a small source image. Set to `false` to disable, which is only safe when modifiers come from a trusted source.\n\n### Filesystem source (`ipxFSStorage`)\n\nEnabled by default with the CLI only.\n\n| Option | Environment variable | Default | Description |\n| ------------------------- | ----------------------------------- | ----------------------- | ------------------------------------------------------ |\n| `dir` | `IPX_FS_DIR` | `.` (current directory) | Directory (or directories) files are served from. |\n| `maxAge` | `IPX_FS_MAX_AGE` | `60` (via `maxAge`) | `cache-control` max-age, in seconds, for served files. |\n| `allowSymlinksOutsideDir` | `IPX_FS_ALLOW_SYMLINKS_OUTSIDE_DIR` | `false` | Allows symlinks inside `dir` to resolve outside of it. |\n\n### HTTP(s) source (`ipxHttpStorage`)\n\nEnabled by default with the CLI only.\n\n| Option | Environment variable | Default | Description |\n| ----------------- | ---------------------------- | ------- | --------------------------------------------------------------- |\n| `domains` | `IPX_HTTP_DOMAINS` | `[]` | Allowlist of hostnames images can be fetched from. |\n| `maxAge` | `IPX_HTTP_MAX_AGE` | `300` | |\n| `fetchOptions` | `IPX_HTTP_FETCH_OPTIONS` | `{}` | Passed to `fetch()`. |\n| `allowAllDomains` | `IPX_HTTP_ALLOW_ALL_DOMAINS` | `false` | Disables the allowlist. Unsafe on a public server. |\n| `blockPrivateIPs` | `IPX_HTTP_BLOCK_PRIVATE_IPS` | `false` | Rejects hosts that are, or resolve to, a non-public IP address. |\n\nOnly `http:` and `https:` URLs are allowed (anything else is rejected with `403 IPX_FORBIDDEN_PROTOCOL`), and redirects are followed **only within the allowlist**, up to 3 hops: each redirect target is re-validated and a redirect to a host that is not listed is rejected with `403 IPX_FORBIDDEN_HOST` (`502 IPX_TOO_MANY_REDIRECTS` beyond 3 hops). Previously redirects were followed blindly, which let an allowlisted host with an open redirect bounce IPX to internal addresses such as the cloud metadata service (SSRF). If an allowlisted host redirects to a CDN, add the CDN hostname to the allowlist as well. Redirect re-validation is skipped when `allowAllDomains` is enabled without `blockPrivateIPs` (nothing to validate) or when `redirect` is explicitly set in `fetchOptions`.\n\n#### Blocking private IP addresses\n\nThe allowlist matches hostnames, not addresses, so an allowlisted host whose DNS record points at `127.0.0.1`, `169.254.169.254` or an RFC1918 address is fetched like any other. That is intended — allowlisted domains are trusted — but `blockPrivateIPs: true` adds a second line of defense for setups where the allowlist is broad (or `allowAllDomains` is on):\n\n```ts\nipxHttpStorage({ domains: [\"cdn.example.com\"], blockPrivateIPs: true });\n```\n\nThe host of the requested URL **and of every redirect hop** must be a public address. IP literals are checked directly, hostnames are resolved with the OS resolver (`dns.lookup`, so `/etc/hosts` counts) and _all_ returned addresses must be public. Loopback, `0.0.0.0/8`, RFC1918, CGNAT (`100.64.0.0/10`), link-local (`169.254.0.0/16`, `fe80::/10`), unique-local (`fc00::/7`), multicast, reserved/test ranges and the IPv4-mapped/compatible IPv6 forms of all of them (`::ffff:127.0.0.1` and friends) are rejected with `403 IPX_FORBIDDEN_IP`. A host that cannot be resolved is a `502 IPX_DNS_LOOKUP_FAILED`, and a runtime without `node:net`/`node:dns` a `500 IPX_IP_CHECK_UNAVAILABLE` — the check fails closed rather than quietly turning itself off.\n\nIt is **off by default**: many deployments legitimately fetch from in-cluster origins (internal object storage, a sidecar, `localhost` in development), and enabling it by default would break them.\n\nTwo limits to be aware of. It does not close the DNS-rebinding window: the name is resolved again when the socket is opened, so a record with a very short TTL can answer with a public address during validation and a private one during the fetch. Closing that requires pinning the validated address on the connection itself, which the plain `fetch` used here does not expose. And it is not a substitute for the allowlist — a public address that happens to be reachable is still fetched.\n\n## SVG Images\n\nSVG images are not processed by sharp. They are sanitized, optimized with [svgo](https://github.com/svg/svgo) and served as `image/svg+xml`. Input that is not well-formed XML (an unescaped `&` is a common cause) is rejected with a `400 IPX_INVALID_SVG`.\n\n```ts\ncreateIPX({\n storage,\n svg: {\n // SVGO config, or `false` to disable optimization\n optimize: { multipass: true },\n // Serve SVG images unsanitized. Only for fully trusted sources!\n unsafeSkipSanitize: false,\n },\n});\n```\n\n### Optimization\n\nSVGO's `preset-default` is applied unless you configure `plugins` yourself. Output is always a re-serialized document, never byte-identical to the source: ids are renamed, elements that are neither visible nor referenced within the same file are dropped, shapes are converted to paths and `![\"IPX](\"./logo.png\"){kind=logo}
![\"/w_160/sample.jpg\"](\"./assets/operations/width.jpg\")
![\"/h_120/sample.jpg\"](\"./assets/operations/height.jpg\")
![\"/s_200x200/sample.jpg\"](\"./assets/operations/resize.jpg\")
![\"/s_80x80,kernel_nearest/sample.jpg\"](\"./assets/operations/kernel.jpg\")
![\"/s_200x200,fit_contain,b_00ff00/sample.jpg\"](\"./assets/operations/fit.jpg\")
![\"/s_200x200,pos_top/sample.jpg\"](\"./assets/operations/position.jpg\")
![\"/extend_20_40_20_40_mirror/sample.jpg\"](\"./assets/operations/extend.jpg\")
![\"/rotate_45,b_00ff00/sample.jpg\"](\"./assets/operations/background.jpg\")
![\"/extract_60_20_180_140/sample.jpg\"](\"./assets/operations/extract.jpg\")
![\"/f_webp/sample.jpg\"](\"./assets/operations/format.webp\")
![\"/q_10/sample.jpg\"](\"./assets/operations/quality.jpg\")
![\"/rotate_45/sample.jpg\"](\"./assets/operations/rotate.jpg\")
![\"/enlarge,s_400x400/sample.jpg\"](\"./assets/operations/enlarge.jpg\")
![\"/flip/sample.jpg\"](\"./assets/operations/flip.jpg\")
![\"/flop/sample.jpg\"](\"./assets/operations/flop.jpg\")
![\"/sharpen_5/sample.jpg\"](\"./assets/operations/sharpen.jpg\")
![\"/median_10/sample.jpg\"](\"./assets/operations/median.jpg\")
![\"/blur_5/sample.jpg\"](\"./assets/operations/blur.jpg\")
![\"/dilate_5/sample-logo.png\"](\"./assets/operations/dilate.png\")
![\"/erode_5/sample-logo.png\"](\"./assets/operations/erode.png\")
![\"/clahe_20_20_5/sample.jpg\"](\"./assets/operations/clahe.jpg\")
![\"/flatten,b_00ff00,f_jpeg/sample-alpha.png\"](\"./assets/operations/flatten.jpg\")
![\"/unflatten,f_webp/sample-logo.png\"](\"./assets/operations/unflatten.webp\")
![\"/gamma_3/sample.jpg\"](\"./assets/operations/gamma.jpg\")
![\"/negate/sample.jpg\"](\"./assets/operations/negate.jpg\")
![\"/normalize_10_90/sample.jpg\"](\"./assets/operations/normalize.jpg\")
![\"/threshold_128/sample.jpg\"](\"./assets/operations/threshold.jpg\")
![\"/linear_1.5_-30/sample.jpg\"](\"./assets/operations/linear.jpg\")
![\"/tint_00ff00/sample.jpg\"](\"./assets/operations/tint.jpg\")
![\"/grayscale/sample.jpg\"](\"./assets/operations/grayscale.jpg\")
![\"/modulate_1.5_2_90_10/sample.jpg\"](\"./assets/operations/modulate.jpg\")
![\"/brightness_1.5/sample.jpg\"](\"./assets/operations/brightness.jpg\")
![\"/saturation_0.3/sample.jpg\"](\"./assets/operations/saturation.jpg\")
![\"/hue_90/sample.jpg\"](\"./assets/operations/hue.jpg\")
![\"/lightness_30/sample.jpg\"](\"./assets/operations/lightness.jpg\")
![\"/opacity_0.5,f_webp/sample.jpg\"](\"./assets/operations/opacity.webp\")
![\"/a,w_160/sample.gif\"](\"./assets/operations/animated.gif\")