Image Optimization

Transformeer en optimaliseer afbeeldingen die vanuit IPFS worden geserveerd on-the-fly met queryparameters. Dit is een openbaar endpoint dat geen authenticatie vereist.

Optimize Image

GET https://api.ipfs.ninja/image/:cid

Geeft de afbeelding bij de opgegeven CID terug, getransformeerd volgens de meegegeven queryparameters. Als er geen transformatieparameters worden opgegeven, leidt het verzoek met een 302-redirect door naar de originele afbeelding op de IPFS-gateway.

Path parameters

Parameter	Type	Required	Description
cid	string	Ja	De IPFS-content identifier van de afbeelding.

Query parameters

Parameter	Type	Default	Description
w	integer	—	Uitvoerbreedte in pixels. Bereik: 1–4096. Waarden ≤ 0 of niet-numeriek worden genegeerd.
h	integer	—	Uitvoerhoogte in pixels. Bereik: 1–4096. Waarden ≤ 0 of niet-numeriek worden genegeerd.
format	string	—	Uitvoerformaat: webp, jpeg, png of avif. Hoofdlettergevoelig (kleine letters). Onbekende waarden worden genegeerd.
quality	integer	80	Compressiekwaliteit, 1–100. Geldt alleen voor webp, jpeg en avif. png is lossless en negeert deze.
fit	string	cover	Hoe de afbeelding in de dimensies past: cover, contain, fill, inside of outside.

Let op: de parameter heet quality, niet q. Veelvoorkomende afkortingen (q, width, height, fmt) worden niet herkend.

Een verzoek dat geen van w, h of format meegeeft, wordt als no-op behandeld en doorgeleid met een 302-redirect naar de originele afbeelding. quality en fit alleen activeren geen transformatie.

Fit modes

Mode	Behavior
cover	Bijsnijden om beide dimensies te bedekken (standaard).
contain	Inpassen binnen beide dimensies met behoud van de beeldverhouding. Kan lege ruimte overlaten (transparant of zwart, afhankelijk van het formaat).
fill	Strekken om beide dimensies exact te vullen. Kan de afbeelding vervormen.
inside	Zoals contain, maar schaalt alleen omlaag, nooit omhoog.
outside	Zoals cover, maar schaalt alleen omlaag, nooit omhoog.

Opschalen

De transformer vergroot een afbeelding nooit boven zijn bronafmetingen. Als je w=2000 opvraagt voor een bron van 1200px breed, is de uitvoer 1200px breed. Dit geldt voor alle fit-modi.

Response

Status	When	Body
200	Transformatie geproduceerd op dit verzoek.	Binaire afbeeldingsbytes. Content-Type komt overeen met het gevraagde formaat.
302	Geen transformatieparameters meegegeven, of een eerder getransformeerd resultaat staat al in de cache.	Location-header verwijst naar de originele afbeelding of het gecachte resultaat op https://ipfs.ninja/image-cache/....
400	cid-padparameter ontbreekt.	{ "error": "cid required" }
404	CID niet gevonden op de gateway.	{ "error": "CID not found" }
500	Onverwachte fout (beschadigde afbeelding, transformatiefout, enz.).	{ "error": "<message>" }

Alle 200- en 302-cacheresponses worden geserveerd met Cache-Control: public, max-age=31536000, immutable. Zie Caching hieronder.

Example requests

Schaal naar 400px breed, converteer naar WebP:

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

Schaal en snijd bij tot 200×200 thumbnail als JPEG met 60% kwaliteit:

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

Vierkante thumbnail met letterboxing in plaats van bijsnijden:

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=200&h=200&format=png&fit=contain"

Alleen formaat converteren, geen formaatwijziging (handig om AVIF/WebP-versies van oude JPEGs te serveren):

curl "https://api.ipfs.ninja/image/QmXmCX9S6ANV...?format=avif&quality=70"

Maximale breedte begrenzen zonder hoogte te forceren (behoudt de beeldverhouding):

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

Using in HTML

Verwijs direct naar geoptimaliseerde afbeeldingen in img-tags:

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

Serveer verschillende formaten met 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"
/>

Moderne formaatonderhandeling met <picture> (AVIF → WebP → JPEG-fallback):

<picture>
  <source
    type="image/avif"
    srcset="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=avif&quality=60"
  />
  <source
    type="image/webp"
    srcset="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=webp&quality=75"
  />
  <img
    src="https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=800&format=jpeg&quality=80"
    alt="IPFS image with format fallback"
  />
</picture>

CSS background-image:

.hero {
  background-image: url("https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=1600&format=webp&quality=70");
}

Gebruik met Next.js

Als custom loader voor next/image:

// loaders/ipfs.js
export default function ipfsLoader({ src, width, quality }) {
  return `https://api.ipfs.ninja/image/${src}?w=${width}&format=webp&quality=${quality || 75}`;
}

import Image from "next/image";
import ipfsLoader from "@/loaders/ipfs";

<Image
  loader={ipfsLoader}
  src="QmXmCX9S6ANV..."
  alt="IPFS image"
  width={800}
  height={600}
/>;

Caching

Responses worden geserveerd met Cache-Control: public, max-age=31536000, immutable. Omdat IPFS-content content-addressed is, levert dezelfde CID met dezelfde parameters altijd dezelfde uitvoer, zodat browsers en CDNs responses oneindig kunnen cachen.

Gecachte transformaties worden opgeslagen in S3, gekoppeld aan de volledige set parameters (cid, w, h, format, quality, fit). Volgende verzoeken met dezelfde parameters geven een 302-redirect terug naar de CloudFront-cache (https://ipfs.ninja/image-cache/...) in plaats van de transformatie opnieuw uit te voeren. Verschillende parametercombinaties produceren verschillende cache-entries.

Availability

Image optimization is beschikbaar op alle plannen, inclusief het gratis Dharma-plan.