Image optimizations
Dedicated IPFS gateways can apply on-the-fly image transformations to JPEG, PNG, WebP, AVIF, GIF, and TIFF responses. Resize, crop, sharpen, rotate, and convert images by passing query parameters in the URL. Animated images are processed as a single frame, and SVG support has additional limitations.
To request image optimization, specify at least one of the img-* parameters below. Start the query string with ? and separate additional parameters with &:
https://my-gateway.myfilebase.com/ipfs/{CID}?img-width=400&img-format=webp&img-quality=75
Use the full parameter names, including the img- prefix. Unprefixed names such as width and quality do not request image transformations.
Supported transforms
| Parameter | Values, defaults, and behavior | Example |
|---|---|---|
img-width | Target width in pixels: a positive integer. Unset by default. | ?img-width=400 |
img-height | Target height in pixels: a positive integer. Unset by default. | ?img-height=300 |
img-dpr | Device pixel ratio: a number greater than 0 and at most 10. Multiplies the requested dimensions. Default: 1. | ?img-width=400&img-dpr=2 |
img-fit | Resize mode: contain (default), scale-down, cover, crop, or pad. | ?img-width=400&img-height=400&img-fit=cover |
img-gravity | Crop position: top, bottom, left, right, center, centre, or auto. Crops are centered when omitted. | ?img-width=400&img-height=400&img-fit=cover&img-gravity=top |
img-quality | Output quality: an integer from 0 to 100. Default: 85. Applies to formats described below. | ?img-quality=75 |
img-format | Output format: auto, webp, jpeg, jpg, or png. Omit to retain the source format. | ?img-format=webp |
img-anim | Default: false. Only the first frame is processed, including when true or 1 is supplied. | ?img-anim=false |
img-rotate | Rotation: auto or an integer from 0 to 360. EXIF orientation is applied automatically; numeric rotation is rounded to a multiple of 90°. | ?img-rotate=90 |
img-sharpen | Sharpening strength: a number from 0 to 10. Default: 0 (no sharpening). | ?img-sharpen=1 |
img-metadata | Metadata preservation: keep or copyright. Metadata is stripped by default; both values preserve it in the same way. | ?img-metadata=keep |
img-onerror | Set to redirect to serve the original response for eligible failures. By default, failures return an error. | ?img-width=400&img-onerror=redirect |
Behavior notes
Sizing and fit
Resizing preserves the image's aspect ratio. With only img-width or img-height, the other dimension follows the source proportions. With both dimensions, img-fit determines how the image fits the target box:
| Fit mode | Behavior |
|---|---|
contain | Fits the entire image within the target box, without cropping or padding. May enlarge the image. This is the default. |
scale-down | Fits the entire image within the target box, without enlarging it. |
cover | Scales the image to fill the target box, then crops the excess. May enlarge the image. |
crop | Scales down and crops to the target box without enlarging. The result can be smaller than the target when the source is too small. |
pad | Fits the entire image within the target box, then adds centered white padding to reach both requested dimensions. May enlarge the image. |
img-dpr multiplies the requested width and height. For example, img-width=400&img-dpr=2 requests a width of 800 pixels. Set at least one dimension to use DPR for resizing.
Source images, intermediate resizing steps, and outputs remain subject to the gateway's configured pixel and file-size limits. A request that exceeds those limits returns an error, including when img-onerror=redirect is set.
Crop position
img-gravity controls which part of the image remains when cropping. top, bottom, left, and right align the crop to that edge; center and centre center it. auto selects a crop based on visually interesting regions.
Explicitly setting right, bottom, left, center, centre, or auto enables cropping and overrides contain or pad behavior. Omitting gravity leaves the fit mode unchanged. top only positions an existing crop, so use it with img-fit=cover or img-fit=crop.
Formats and quality
img-format=auto selects WebP. Use jpeg or jpg for JPEG, png for PNG, and webp for WebP. If img-format is omitted, the source format is retained.
AVIF, GIF, and TIFF are accepted input formats but are not selectable conversion targets through img-format. When the output is JPEG, WebP, AVIF, or TIFF, img-quality is passed to that format's encoder. It does not control PNG or GIF output.
SVG support is limited by the source response's Content-Type. The gateway currently accepts image/svg for image processing; the standard image/svg+xml content type is rejected as an unsupported input type. For accepted SVG input, omitting img-format returns the SVG unchanged, so other transformations are not applied. Specify a supported output format to request conversion.
Animation
Image optimization processes only the first frame of an animated image. img-anim=false describes the default behavior. Although true and 1 are accepted as parameter values, they do not preserve animation.
Rotation
EXIF orientation is applied automatically before resizing, including when img-rotate is omitted or set to auto. A numeric rotation is applied after resizing.
Numeric values are rounded to the nearest multiple of 90°, with halfway values rounded down: for example, 45° becomes 0° and 135° becomes 90°. Use 0, 90, 180, 270, or 360 for predictable quarter turns; 0 and 360 add no rotation.
Metadata
Metadata is stripped by default. Set img-metadata=keep to preserve metadata supported by the output format. img-metadata=copyright currently has the same preservation behavior as keep: it does not filter metadata to copyright fields.
Error fallback
img-onerror=redirect serves the original response inline if image processing fails or the source content type is unsupported. Despite its name, it does not issue an HTTP redirect.
Fallback does not bypass parameter validation, image-size limits, worker admission failures, or upstream retrieval errors. These still return errors.
Examples
# Original
https://my-gateway.myfilebase.com/ipfs/{CID}
# 400px wide
https://my-gateway.myfilebase.com/ipfs/{CID}?img-width=400
# WebP with quality set to 75
https://my-gateway.myfilebase.com/ipfs/{CID}?img-format=webp&img-quality=75
# 400x400 cover crop
https://my-gateway.myfilebase.com/ipfs/{CID}?img-width=400&img-height=400&img-fit=cover
# 400px target width at DPR 2 (800px output), converted to WebP
https://my-gateway.myfilebase.com/ipfs/{CID}?img-width=400&img-dpr=2&img-format=webp
# Resize, convert to WebP, set quality, and sharpen
https://my-gateway.myfilebase.com/ipfs/{CID}?img-width=400&img-format=webp&img-quality=75&img-sharpen=1
Caching
Use the complete image URL, including its query parameters, when identifying an image variant in your application's cache. Follow the response's Cache-Control headers to determine whether and how long a response can be cached. Reusing a URL does not guarantee that the gateway will skip image processing.