How to Resize Images Using URL Parameters on AIOZ Pin

To resize images using URL parameters on AIOZ Pin, add img- query parameters to the gateway link that already serves your pinned image. For example, ?img-width=400&img-fit=cover returns a 400-pixel version. You don't upload a copy, call an API, or send an API key.

TL;DR:

• Any image pinned on AIOZ Pin can be resized, cropped, compressed, or served as WebP by changing its gateway URL.
• There are 11 documented parameters, from img-width and img-fit to img-format=webp and img-onerror=redirect. At least one must be set.
• Supported formats are BMP, GIF, JPG/JPEG, PNG, and WebP. The public gateway needs no authentication for this.
• The payment page lists no separate fee for transforms. You pay storage and bandwidth as usual.

Updated Oct 19, 2026: added the img-format=webp option and corrected defaults (img-metadata is copyright, img-gravity is center, img-dpr tops out at 3). Also new: a fit-mode diagram, a way to measure the savings, the SDK's optimizeImage, and use cases from our image optimization overview.

How do you resize an image with URL parameters?

Every file you pin is reachable at https://<gateway>.aiozpin.network/ipfs/<CID>, where the gateway is public or your own premium subdomain. Add query parameters to that URL and the gateway returns a transformed image, built at request time. The original stays pinned once, unchanged. This is the example from the AIOZ Pin image optimization docs:

https://premium.aiozpin.network/ipfs/bafkreiefnp4dflv35vsqzrnp25woubdbylgesttpanq6dfkctbhgo3lvy4?img-width=300&img-height=600&img-fit=cover

That URL asks for an image no wider than 300 pixels and no taller than 600, cropped to fill the box. Request the same CID with no parameters and you get the original file. The docs say at least one option must be set for optimization to run.

This matters because an original photo is often far larger than the slot it fills. A 4,000-pixel camera shot shown in a 400-pixel card wastes most of its bytes. Sending each placement the size it needs cuts transfer, which speeds up pages and lowers your bandwidth bill.

What does each img- parameter do?

The gateway docs list 11 options. Defaults below come from the gateway docs. The img-anim default comes from the API reference, since the gateway page doesn't give one.

Two details trip people up. img-quality only affects JPEG and WebP, so it does nothing to a PNG unless you also convert with img-format=webp. And img-metadata defaults to copyright, which strips GPS and camera data but keeps copyright fields. Use keep only if you want location data public.

Which img-fit mode should you use?

img-fit decides what happens when your box doesn't match the photo's shape. All five modes keep the aspect ratio. The diagram shows what each one does with a 1600 x 900 photo and a 600 x 600 request.

• scale-down (the default) shrinks the image to fit but never enlarges it. It's the safe choice for general resizing.
• contain scales up or down to fit inside the box. Use it for logos and anything that must not be cropped.
• cover fills the box and may crop. Use it for hero banners and fixed-shape cards, and set img-gravity to keep the subject.
• crop acts like scale-down for small images and like cover for large ones. It suits thumbnail grids with mixed source sizes.
• pad fits the image and fills the rest, usually with white. For a transparent look, the docs suggest CSS object-fit: contain instead.

With cover, img-gravity=auto picks the main focus area for you. Use top, left, and so on, or a coordinate such as 0.5x0.2, when you know where the subject sits.

Building a responsive image set

Because the transform is only a query string, a standard srcset works with no build step. One pinned file and one CID give you three delivered sizes, and the browser picks the one that fits:

<img
  src="https://<gateway>.aiozpin.network/ipfs/<CID>?img-width=800&img-format=webp"
  srcset="
    https://<gateway>.aiozpin.network/ipfs/<CID>?img-width=400&img-format=webp 400w,
    https://<gateway>.aiozpin.network/ipfs/<CID>?img-width=800&img-format=webp 800w,
    https://<gateway>.aiozpin.network/ipfs/<CID>?img-width=1200&img-format=webp 1200w
  "
  sizes="(max-width: 600px) 400px, 800px"
  alt="Product photo"
/>

For a single fixed-size image on high-density screens, ?img-width=400&img-dpr=2 does the job with less markup. It serves an 800-pixel image that you display at 400 CSS pixels.

Measuring the savings on your own images

We don't publish before-and-after numbers here, because savings depend on your source files. You can measure them in two requests. Compare the byte count of the original with a resized copy of the same CID (commands from the documented URL format, not run here):

# Original bytes
curl -s -o original -w '%{size_download} bytes\n' "https://public.aiozpin.network/ipfs/<CID>"

# Same CID at 400 px wide, quality 50, WebP for browsers that accept it
curl -s -o small -H 'Accept: image/webp' -w '%{size_download} bytes\n' \
  "https://public.aiozpin.network/ipfs/<CID>?img-width=400&img-quality=50&img-format=webp"

Run it on a few typical images, a large photo, a PNG screenshot, and a GIF, to see where transforms pay off. Keep the public gateway's limits in mind while testing: 15 requests per minute per CID and 200 per minute per IP.

Handling errors without a broken image icon

img-onerror=redirect tells the gateway to send the original file if optimization fails, instead of an error. On a production <img> tag, that's the difference between a broken-image icon and a full-size image that still loads. Set it on anything user-facing where an odd source file could otherwise break your layout.

Where gateway resizing helps most

• NFT galleries: small thumbnails in the grid, the full image on the detail page, all from one CID.
• Product grids: cover plus img-gravity gives every card the same shape, whatever the source.
• Docs and blogs: screenshots served at reading width instead of full monitor size.
• Share previews: a fixed 1200 x 630 crop for link cards, without a second upload.

It isn't a full image pipeline. The docs list no SVG support, no video thumbnails, and no subject detection beyond img-gravity=auto. For those, you still need a separate service.

How AIOZ Pin handles image resizing

Resizing runs on our gateways, for content pinned on AIOZ Pin. The public gateway needs no authentication, so URLs drop straight into HTML or CSS, which can't send headers. It's meant for testing, though. For production traffic, a premium gateway has no predefined rate limit and serves from 200+ edge caching locations. Free plan users get a limited premium gateway that serves single files such as images, which covers this use.

From Node.js, the SDK wraps the same options in optimizeImage and returns the image bytes. This is the README example for version 1.0.1, lightly trimmed (not run here):

import { writeFileSync } from 'fs'

const result = await client.optimizeImage({
  cid: 'YOUR CID',
  gatewayProviderUrl: 'GATEWAY URL',
  config: { imgWidth: 800, imgQuality: 75, imgFit: 'cover', imgGravity: '0.5x0.5' },
  axiosConfig: { responseType: 'arraybuffer' }
})
writeFileSync('optimized-image.jpg', Buffer.from(result))

There's no separate line item for transforms on the payment page. Storage is $20 per TB per month and bandwidth $20 per TB, so a smaller image also costs you less to serve.

Next step: read the AIOZ Pin image optimization docs and try a parameter on one of your pinned images.

Frequently Asked Questions

How do I resize an image using URL parameters on AIOZ Pin? Add img-width, img-height, and optionally img-fit to the gateway URL, for example https://public.aiozpin.network/ipfs/<CID>?img-width=400.

Do I need an API key to resize images? No. The docs say public gateway image optimization needs no authentication, so the URL works directly in an <img> tag.

Which image formats are supported? BMP, GIF, JPG/JPEG, PNG, and WebP. There's no SVG support in the list.

Can AIOZ Pin convert images to WebP? Yes. Add img-format=webp and the gateway serves WebP to browsers that support it, falling back to standard formats otherwise.

Does resizing cost extra? The payment page lists storage, bandwidth, and pinned-file fees, with no separate charge for transforms. Resized images are served as normal gateway bandwidth.

What happens if a transform fails? By default you get an error. Add img-onerror=redirect and the gateway serves the original image instead.

Related Reading

• AIOZ Pin Dedicated Gateways - the public vs premium gateway choice this feature runs on
• How AIOZ Pin Billing Works - where transformed images fall in the pricing model
• AIOZ Pin for Developers: API, SDK, and CLI Explained - where image optimization sits among the API sections
• How an IPFS gateway works - the general gateway mechanics behind this feature
• How AIOZ Pin Works - the three components, including Premium Gateways

References

• AIOZ Pin Image Optimizations (gateway docs)
• AIOZ Pin Image Optimization API reference
• AIOZ Pin Limit documentation
• AIOZ Pin Premium Gateways documentation
• @aioznetwork/aioz-pin-sdk on npm