Image Optimization on AIOZ Pin: Smarter Image Delivery from IPFS

Images are often the heaviest assets on a modern site or app, and large files directly increase page load time, especially on galleries, documentation sites, product pages, and NFT platforms. AIOZ Pin's Image Optimization is a gateway-side capability that generates the right image version at request time, so a single pinned original can serve every placement it needs to without keeping multiple versions in storage.

TL;DR:

• Image Optimization runs at the AIOZ Pin gateway, not at upload time, so you pin one source image and the gateway generates the version a specific request actually needs
• It's driven by real, documented img- query parameters, width, height, fit mode, quality, DPR, sharpening, and more, appended directly to the gateway URL
• Right-sizing and format-appropriate delivery are what actually drive the performance gain, not a vague "optimization" claim
• No separate upload workflow is needed. Every variant is generated from the same IPFS-hosted source file
• It's especially useful for NFT galleries, product grids, documentation sites, and any Web3 app serving many images across different layouts

What Image Optimization Actually Does

Image Optimization on AIOZ Pin is a gateway-side service for content already pinned to AIOZ Pin. When a browser requests an image, the gateway can dynamically generate an optimized version, resizing it, adjusting how it fits its layout, tuning compression quality, handling metadata, optionally preserving GIF animation, and applying light sharpening. Instead of storing multiple pre-rendered versions in advance, you keep a single source asset on IPFS, and the gateway produces the right version for each request, a thumbnail, a grid image, a full-width hero banner, on demand.

The Real Parameters Behind It

This isn't an abstract "smart delivery" feature, it's driven by specific img- query parameters appended to a gateway URL. The ones that matter most in practice:

• img-width / img-height - target dimensions in pixels; 0 keeps the original for that dimension
• img-fit - resize behavior: scale-down, contain, cover, crop, or pad
• img-quality - compression quality from 0 to 100, applied to JPG and WebP
• img-dpr - a device-pixel-ratio multiplier for sharper images on high-resolution displays
• img-sharpen - sharpening strength, 0 to 10
• img-anim - whether to preserve GIF animation frames
• img-metadata - EXIF handling: keep, copyright, or none

A request with none of these set simply returns the original image unchanged, nothing happens until you actually set a parameter. The full parameter reference, including gravity control and fallback behavior, is covered in depth in this series' dedicated resizing guide, linked below.

Why It Matters

As IPFS adoption grows, more teams are serving real, user-facing products directly from decentralized storage, and Image Optimization helps bridge that decentralized content with modern performance expectations. Moving optimization to the gateway layer means teams can simplify their workflows, avoid maintaining duplicate pre-rendered assets, and deliver faster, more responsive experiences without changing anything about how content actually gets stored on IPFS.

How It Actually Improves Performance

Two factors drive most of the improvement:

Right-sizing. Original images are often far larger than what a page actually displays. Returning an image that matches the dimensions a placement actually needs cuts unnecessary data transfer directly.

Placement-appropriate delivery. A thumbnail doesn't need the same size or detail as a full-width banner. Gateway-side optimization means each placement can receive an image fitted to its own layout and purpose, rather than one oversized original getting scaled down in the browser.

The result is faster page loads, better visual stability, and lower bandwidth usage, especially across image-heavy products like NFT galleries or product catalogs.

Real-World Use Cases

• NFT galleries and previews - fast-loading thumbnails that open into crisp full-resolution detail
• Product grids and cards - consistent layouts with lightweight images
• Documentation sites and blogs - improved page load speed and reading experience
• Web3 apps and dashboards - efficient delivery across a range of devices and screen sizes
• Social and sharing visuals - predictable image dimensions for link previews

Combining Parameters in One Request

Parameters compose, so a single gateway URL can handle sizing, cropping, and quality together in one request. A product-card image request might look like:

https://premium.aiozpin.network/ipfs/{CID}?img-width=400&img-height=300&img-fit=cover&img-quality=80

That single URL crops to a 400x300 card, fills the frame without distortion (cover), and compresses to quality 80, all generated from the same pinned source file, no separate upload or pre-processing step required for that specific size.

Getting Started

1. Pin your high-quality source image on AIOZ Pin
2. Define a small set of sensible presets, for example card, hero, and avatar sizes
3. Test each preset by appending the relevant img- parameters to your gateway URL
4. Replace original image links in your CMS, docs, or frontend with the optimized versions
5. Monitor load times and bandwidth to confirm the improvement in practice

Frequently Asked Questions

Do I need to upload multiple versions of an image to use this? No. You pin a single source image, and the gateway generates each requested variant on demand using the img- query parameters in the URL.

What happens if I request an image with no parameters set? Nothing changes, img-width and img-height default to 0, meaning "don't resize," so an unparameterized request just returns the original image.

Does this work on animated GIFs? Yes, animation frames can be preserved using the img-anim parameter rather than being flattened to a single static frame.

Where does the optimization actually happen? At the AIOZ Pin gateway, at request time, not at upload time and not through a separate image-processing pipeline you have to maintain yourself.

What's the difference between this and just resizing an image before uploading it? Pre-resizing locks you into whatever sizes you generated in advance. Gateway-side optimization generates the exact size and fit each request needs from one source file, without maintaining separate pre-rendered versions.

Related Reading

• How to Resize Images on AIOZ Pin Using URL Parameters - the full img- parameter reference, fit-mode table, and a working example
• How AIOZ Pin Works: Pinning, Gateways, and NFT Tools - where Image Optimization fits among AIOZ Pin's other gateway features
• AIOZ Pin Dedicated Gateways: Simple, High-Performance IPFS Access - the gateway infrastructure this feature runs on
• AIOZ Pin for Developers: API, SDK, and CLI Explained - where the Image Optimization API section fits among AIOZ Pin's other tooling
• How to Mint NFTs with Persistent Metadata on AIOZ Pin - one of the real use cases this feature's NFT-gallery example refers to

References

• AIOZ Pin Docs: Image Optimization