Image Optimization

Transform and optimize images served from IPFS on-the-fly using query parameters. This is a public endpoint that requires no authentication.

Optimize Image

GET /image/:cid

Returns the image at the given CID, transformed according to the provided query parameters. If no parameters are provided, the request redirects to the original image.

Path parameters

Parameter	Type	Required	Description
cid	string	Yes	The IPFS content identifier of the image.

Query parameters

Parameter	Type	Default	Description
w	number	—	Output width in pixels. Max 4096.
h	number	—	Output height in pixels. Max 4096.
format	string	—	Output format: webp, jpeg, png, or avif.
quality	number	80	Compression quality, 1-100. Only applies when format is set.
fit	string	cover	How the image should fit the dimensions: cover, contain, fill, inside, or outside.

Fit modes

Mode	Behavior
cover	Crop to cover both dimensions (default).
contain	Fit within both dimensions, preserving aspect ratio. May leave empty space.
fill	Stretch to fill both dimensions exactly. May distort the image.
inside	Like contain, but only scales down, never up.
outside	Like cover, but only scales down, never up.

Example requests

Resize to 400px wide, convert to WebP:

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=400&format=webp"

Resize and crop to 200x200 thumbnail as JPEG at 60% quality:

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=200&h=200&format=jpeg&quality=60&fit=cover"

Using in HTML

Reference optimized images directly in img tags:

<img
  src="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=webp&quality=75"
  alt="Optimized IPFS image"
/>

Serve different sizes with srcset:

<img
  srcset="
    https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=400&format=webp 400w,
    https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=webp 800w,
    https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=1200&format=webp 1200w
  "
  sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
  src="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=webp"
  alt="Responsive IPFS image"
/>

Caching

Responses are served with immutable cache headers. Since IPFS content is content-addressed, the same CID with the same parameters always produces the same output. Browsers and CDNs can cache these responses indefinitely.

Availability

Image optimization is available on all plans, including the free Dharma plan.