Guide: Image Optimization via Gateway

Optimize Images Without Reprocessing Them

Filebase Dedicated IPFS Gateways can resize and optimize images at request time. Instead of storing several versions of the same file, you keep the original image on IPFS and add query parameters to the gateway URL when you need a different size, format, or quality level.

This works for images you have pinned in your Filebase account and for images loaded through the public IPFS network, as long as they are being served through a Filebase dedicated gateway.

How It Works

Image optimization is URL-driven. You start with a dedicated gateway URL that points at an image, then append one or more query parameters. Filebase applies those transformations on the fly before returning the image.

For example, to request a resized image:

https://my-gateway.myfilebase.com/ipfs/QmYourImageCid?img-width=300

At least one image option has to be present for the optimization flow to run.

Combine Parameters in a Single Request

You can pass multiple query parameters in the same URL to stack transformations. For example:

https://my-gateway.myfilebase.com/ipfs/QmYourImageCid?img-height=200&img-sharpen=10

This makes it easy to generate delivery-specific image variants without changing the underlying CID.

Core Options

• img-width=x: sets the maximum width in pixels.
• img-height=x: sets the maximum height in pixels.
• img-dpr=x: sets the device pixel ratio. The default is 1.
• img-quality=x: controls JPEG and WebP quality.
• img-format=auto: controls output format. The docs note support for standard image formats including JPEG, PNG, and WebP, with JPEG/PNG as the default behavior when no format is specified.
• img-sharpen=x: applies a sharpening filter from 0 to 10.
• img-anim=false: reduces frames for animated images such as GIFs.
• img-metadata: controls metadata retention.

Fit and Gravity Controls

If you are resizing with both width and height, you can control how the image fits the requested dimensions with img-fit.

• img-fit=scale-down: reduces the image to fit within the requested bounds.
• img-fit=contain: keeps the full image visible inside the requested box.
• img-fit=cover: fills the requested dimensions.
• img-fit=crop: downsizes and crops the image to match the requested size.
• img-fit=pad: resizes within the bounds and pads the result.

The docs also expose img-gravity for positioning decisions, including img-gravity=auto and directional or coordinate values.

Practical Examples

Convert an image to WebP:

https://my-gateway.myfilebase.com/ipfs/QmYourImageCid?img-format=webp

Compress an image by setting quality to 80:

https://my-gateway.myfilebase.com/ipfs/QmYourImageCid?img-quality=80

Resize, convert, and compress in one request:

https://my-gateway.myfilebase.com/ipfs/QmYourImageCid?img-width=300&img-height=300&img-format=jpeg&img-quality=90

Best Practices

• Resize images to the dimensions your UI actually needs.
• Use modern formats like WebP when browser support allows it.
• Adjust img-quality to find the right balance between file size and visual fidelity.
• Keep one original asset on IPFS and generate delivery variants through query parameters instead of storing many copies.

When to Use It

This feature is useful anywhere you need responsive image delivery: marketing sites, dashboards, documentation portals, image-heavy apps, and any frontend that needs smaller or format-specific assets at the edge.

If you already serve content through a Filebase dedicated gateway, image optimization lets you improve payload size and page speed without changing how your assets are stored.

For the full parameter reference, see the official Filebase documentation.