Bildoptimierung

Transformieren und optimieren Sie Bilder von IPFS on-the-fly mithilfe von Abfrageparametern. Dies ist ein öffentlicher Endpunkt, der keine Authentifizierung erfordert.

Bild optimieren

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

Gibt das Bild mit dem angegebenen CID zurück, transformiert gemäß den bereitgestellten Abfrageparametern. Wenn keine Transformationsparameter angegeben werden, leitet die Anfrage per 302-Redirect zum Originalbild auf dem IPFS-Gateway weiter.

Pfadparameter

Parameter	Typ	Erforderlich	Beschreibung
cid	string	Ja	Der IPFS Content Identifier des Bildes.

Abfrageparameter

Parameter	Typ	Standard	Beschreibung
w	integer	—	Ausgabebreite in Pixel. Bereich: 1–4096. Werte ≤ 0 oder nicht-numerische Werte werden ignoriert.
h	integer	—	Ausgabehöhe in Pixel. Bereich: 1–4096. Werte ≤ 0 oder nicht-numerische Werte werden ignoriert.
format	string	—	Ausgabeformat: webp, jpeg, png oder avif. Groß-/Kleinschreibung beachten (Kleinbuchstaben). Unbekannte Werte werden ignoriert.
quality	integer	80	Komprimierungsqualität, 1–100. Gilt nur für webp, jpeg und avif. png ist verlustfrei und ignoriert diesen Wert.
fit	string	cover	Wie das Bild in die Dimensionen eingepasst werden soll: cover, contain, fill, inside oder outside.

Hinweis: Der Parameter heißt quality, nicht q. Gängige Kurzformen (q, width, height, fmt) werden nicht erkannt.

Eine Anfrage, die weder w, h noch format enthält, wird als No-Op behandelt und per 302-Redirect zum Originalbild umgeleitet. quality und fit allein lösen keine Transformation aus.

Einpassungsmodi

Modus	Verhalten
cover	Zuschneiden, um beide Dimensionen abzudecken (Standard).
contain	In beide Dimensionen einpassen, Seitenverhältnis beibehalten. Kann leeren Raum hinterlassen (transparent oder schwarz, je nach Format).
fill	Auf beide Dimensionen exakt strecken. Kann das Bild verzerren.
inside	Wie contain, skaliert aber nur herunter, nie hoch.
outside	Wie cover, skaliert aber nur herunter, nie hoch.

Hochskalierung

Der Transformator vergrößert ein Bild niemals über seine Quellabmessungen hinaus. Wenn Sie w=2000 für eine 1200px breite Quelle anfordern, ist die Ausgabe 1200px breit. Dies gilt für alle fit-Modi.

Antwort

Status	Wann	Body
200	Transformation wurde bei dieser Anfrage erzeugt.	Binäre Bilddaten. Content-Type entspricht dem angeforderten Format.
302	Keine Transformationsparameter angegeben oder ein zuvor transformiertes Ergebnis ist bereits zwischengespeichert.	Location-Header verweist auf das Originalbild oder das gecachte Ergebnis unter https://ipfs.ninja/image-cache/....
400	cid-Pfadparameter fehlt.	{ "error": "cid required" }
404	CID auf dem Gateway nicht gefunden.	{ "error": "CID not found" }
500	Unerwarteter Fehler (beschädigtes Bild, fehlgeschlagene Transformation usw.).	{ "error": "<message>" }

Alle 200- und 302-Cache-Antworten werden mit Cache-Control: public, max-age=31536000, immutable ausgeliefert. Siehe Caching unten.

Beispielanfragen

Auf 400px Breite skalieren, in WebP konvertieren:

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

Skalieren und auf 200×200 Vorschaubild als JPEG mit 60% Qualität zuschneiden:

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

Quadratisches Vorschaubild mit Letterboxing statt Zuschneiden:

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

Nur Format konvertieren, keine Größenänderung (nützlich, um AVIF/WebP-Versionen älterer JPEGs auszuliefern):

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

Maximale Breite begrenzen, ohne die Höhe zu erzwingen (Seitenverhältnis bleibt erhalten):

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

Verwendung in HTML

Referenzieren Sie optimierte Bilder direkt in img-Tags:

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

Stellen Sie verschiedene Größen mit srcset bereit:

<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 Format-Aushandlung mit <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");
}

Verwendung mit Next.js

Als benutzerdefinierter Loader für 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

Antworten werden mit Cache-Control: public, max-age=31536000, immutable ausgeliefert. Da IPFS-Inhalte inhaltsadressiert sind, erzeugt derselbe CID mit denselben Parametern immer dieselbe Ausgabe, sodass Browser und CDNs Antworten unbegrenzt zwischenspeichern können.

Zwischengespeicherte Transformationen werden in S3 abgelegt und über den vollständigen Parametersatz (cid, w, h, format, quality, fit) indiziert. Folgeanfragen mit denselben Parametern liefern einen 302-Redirect zum CloudFront-gestützten Cache (https://ipfs.ninja/image-cache/...) zurück, statt die Transformation erneut auszuführen. Unterschiedliche Parameterkombinationen erzeugen unterschiedliche Cache-Einträge.

Verfügbarkeit

Bildoptimierung ist in allen Plänen verfügbar, einschließlich des kostenlosen Dharma-Plans.