How to Resize Images on AIOZ Pin Using URL Parameters

AIOZ Pin image resizing happens entirely in the URL, not through an upload dashboard or a separate transformation call, it is a set of query parameters appended to the exact same gateway link that already serves your pinned file. That means any image already pinned on AIOZ Pin can be resized, cropped, compressed, or format-converted just by changing the query string in an <img src> tag, with no extra request and no separate service to configure. This covers every documented img- parameter, what it actually controls, and two real examples: building a responsive image set and picking the right fit mode for a layout.

TL;DR:

• AIOZ Pin resizes, crops, compresses, and converts images directly from the gateway URL using img- query parameters, no upload step or separate API call
• Ten parameters control the transform: width, height, fit mode, gravity, quality, DPR, sharpen, animation, metadata, and an error fallback
• The endpoint is a plain, unauthenticated GET (https://{gateway}.aiozpin.network/ipfs/{cid}?img-width=400), so it drops straight into an <img src> tag with no headers to attach
• Supported formats are BMP, GIF, JPG, PNG, and WebP; AIOZ Pin's pricing docs list storage, bandwidth, and pinned-file fees but no separate charge for image transforms

How AIOZ Pin's Image Resizing Actually Works

Every pinned file on AIOZ Pin is already reachable at https://{gateway}.aiozpin.network/ipfs/{cid}, where gateway is either public or premium. Image resizing works by appending query parameters to that same URL, nothing about the base request changes. Request the file plain and you get the original; add ?img-width=400&img-fit=cover and the gateway returns a resized, cropped version instead, computed on the fly rather than stored as a separate pinned copy.

This is worth noting because it differs from how the Gateways list endpoint and the NFT API authenticate: those expect pinning_api_key/pinning_secret_key headers. The image transform endpoint documents no headers at all, which makes sense once you consider where it actually gets used, directly inside an <img src> or a CSS background-image, neither of which can attach a custom header. If it required a key, it couldn't be dropped straight into HTML.

The Full List of img- Parameters

Only img-width and img-height have documented defaults of 0 (meaning "don't resize this dimension"), so a request with no parameters at all just returns the original image unchanged. Everything else only takes effect once you set it.

Building a Responsive Image Set

Because the transform is just a query string, a standard srcset works without any build-time image processing:

<img
  src="https://premium.aiozpin.network/ipfs/bafybeig.../photo.jpg?img-width=800&img-quality=80"
  srcset="
    https://premium.aiozpin.network/ipfs/bafybeig.../photo.jpg?img-width=400&img-quality=80 400w,
    https://premium.aiozpin.network/ipfs/bafybeig.../photo.jpg?img-width=800&img-quality=80 800w,
    https://premium.aiozpin.network/ipfs/bafybeig.../photo.jpg?img-width=1200&img-quality=80 1200w
  "
  sizes="(max-width: 600px) 400px, 800px"
  alt="Product photo"
/>

One pinned file, one CID, three delivered sizes, the browser picks whichever srcset entry fits the viewport. For a fixed-size retina image instead of a full srcset, img-dpr=2 on a single URL does the same job with less markup: ?img-width=400&img-dpr=2 serves an 800px-wide image sized to display at 400 CSS pixels, which is the standard way to keep a logo or icon sharp on high-density screens without doubling the layout width.

Picking the Right Fit Mode

img-fit decides what happens when the target dimensions do not match the source image's aspect ratio:

cover and crop both cut off part of the source image, which is where img-gravity matters: set it to auto for content-aware cropping, or to top/left/etc. (or an explicit XxY coordinate) when you know exactly which part of the image has to survive, a product on a busy background, a logo pinned to one corner, a face near the top of a portrait.

Handling Errors Without a Broken Image Icon

img-onerror=redirect tells the gateway to fall back to serving the original, untransformed file if the requested resize fails for any reason, rather than returning an error response. For a production <img> tag, this is the difference between a broken-image icon and a slightly-wrong-size image, worth setting on anything user-facing where a malformed parameter or an edge-case source file could otherwise break the layout silently.

What This Replaces, and What It Doesn't

For standard resize, crop, quality, and format needs, this removes the case for running a separate image CDN or transformation service in front of pinned content, one gateway URL already does the resizing, and AIOZ Pin's pricing documentation lists storage, bandwidth, and pinned-file fees with no separate line item for image transforms, so these requests are billed the same as any other gateway request. It is not a full image pipeline: there is no face-detection cropping beyond the auto gravity setting, no thumbnail generation for video, and no vector format in the supported list (BMP, GIF, JPG, PNG, and WebP only, no SVG). For anything beyond resize/crop/compress/format-convert, you still need a dedicated service.

Frequently Asked Questions

What is AIOZ Pin's image resizing feature? A set of img- query parameters appended to a pinned file's gateway URL that resize, crop, compress, or format-convert the image on the fly, with no separate upload or API call.

Do I need an API key to resize an image on AIOZ Pin? No. The endpoint is a plain, unauthenticated GET request, since it is designed to be used directly inside an <img src> or CSS background-image, neither of which can send custom headers.

What image formats does AIOZ Pin's resizing support? BMP, GIF, JPG, PNG, and WebP. There is no SVG or video thumbnail support.

Does resizing images on AIOZ Pin cost extra? AIOZ Pin's pricing documentation lists storage, bandwidth, and pinned-file fees with no separate charge for image transforms, so these requests are billed under standard gateway bandwidth pricing.

How do I serve a sharp image on high-density screens without a full srcset? Add img-dpr=2 (or higher) to a single URL alongside img-width, it multiplies the delivered resolution while the display size in CSS stays the same.

What happens if an image transform request fails? By default it returns an error. Adding img-onerror=redirect falls back to serving the original, untransformed file instead.

Related Reading

• AIOZ Pin Dedicated Gateways: Simple, High-Performance IPFS Access - the public vs. premium gateway distinction this feature runs on top of
• How AIOZ Pin Billing Works: Storage, Bandwidth, and Pinned Files Explained - where image transform requests fall in AIOZ Pin's pricing model
• AIOZ Pin for Developers: API, SDK, and CLI Explained - how this endpoint fits among AIOZ Pin's other API sections
• Image Optimization on AIOZ Pin: Smarter Image Delivery from IPFS - the feature overview and use cases this parameter reference supports
• Explore How IPFS Gateway Works Across Decentralized Networks - the general gateway mechanics this feature runs on top of, independent of AIOZ Pin specifically

References

• AIOZ Pin Image Optimization Documentation
• AIOZ Pin Gateways Documentation