Bildoptimering

Transformera och optimera bilder som serveras från IPFS direkt med frågeparametrar. Detta är en offentlig endpoint som inte kräver autentisering.

Optimera bild

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

Returnerar bilden vid angiven CID, transformerad enligt angivna frågeparametrar. Om inga transformationsparametrar anges, omdirigeras begäran med en 302-redirect till originalbilden på IPFS-gatewayen.

Sökvägsparametrar

Parameter	Typ	Obligatorisk	Beskrivning
cid	string	Ja	Bildens IPFS-innehållsidentifierare.

Frågeparametrar

Parameter	Typ	Standard	Beskrivning
w	integer	—	Utdatabredd i pixlar. Intervall: 1–4096. Värden ≤ 0 eller icke-numeriska ignoreras.
h	integer	—	Utdatahöjd i pixlar. Intervall: 1–4096. Värden ≤ 0 eller icke-numeriska ignoreras.
format	string	—	Utdataformat: webp, jpeg, png eller avif. Skiftlägeskänsligt (gemener). Okända värden ignoreras.
quality	integer	80	Komprimeringskvalitet, 1–100. Gäller endast för webp, jpeg och avif. png är förlustfritt och ignorerar detta.
fit	string	cover	Hur bilden ska passa dimensionerna: cover, contain, fill, inside eller outside.

Obs: parametern heter quality, inte q. Vanliga förkortningar (q, width, height, fmt) känns inte igen.

En begäran som inte innehåller någon av w, h eller format behandlas som en no-op och omdirigeras med en 302-redirect till originalbilden. quality och fit ensamma utlöser ingen transformation.

Passningslägen

Läge	Beteende
cover	Beskär för att täcka båda dimensionerna (standard).
contain	Passa inom båda dimensionerna, bevara bildförhållandet. Kan lämna tomt utrymme (transparent eller svart beroende på format).
fill	Sträck för att fylla båda dimensionerna exakt. Kan förvränga bilden.
inside	Som contain, men skalar bara ner, aldrig upp.
outside	Som cover, men skalar bara ner, aldrig upp.

Uppskalning

Transformeraren förstorar aldrig en bild bortom dess källdimensioner. Om du begär w=2000 för en källa som är 1200px bred, blir utdata 1200px bred. Detta gäller alla fit-lägen.

Svar

Status	När	Body
200	Transformation producerades vid denna begäran.	Binära bilddata. Content-Type matchar det begärda formatet.
302	Inga transformationsparametrar angavs, eller ett tidigare transformerat resultat är redan cachat.	Location-header pekar på originalbilden eller det cachade resultatet på https://ipfs.ninja/image-cache/....
400	cid-sökvägsparameter saknas.	{ "error": "cid required" }
404	CID hittades inte på gatewayen.	{ "error": "CID not found" }
500	Oväntat fel (skadad bild, transformationsfel osv.).	{ "error": "<message>" }

Alla 200- och 302-cachesvar serveras med Cache-Control: public, max-age=31536000, immutable. Se Cache nedan.

Exempelbegäranden

Ändra storlek till 400px bred, konvertera till WebP:

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

Ändra storlek och beskär till 200×200 miniatyr som JPEG med 60% kvalitet:

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

Kvadratisk miniatyr med letterboxing i stället för beskärning:

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

Konvertera endast format, ingen storleksändring (användbart för att leverera AVIF/WebP-versioner av äldre JPEG):

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

Begränsa maximal bredd utan att tvinga höjd (bevarar bildförhållandet):

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

Användning i HTML

Referera optimerade bilder direkt i img-taggar:

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

Servera olika storlekar med 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="Responsiv IPFS-bild"
/>

Modern formatförhandling med <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");
}

Användning med Next.js

Som anpassad 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}
/>;

Cache

Svar serveras med Cache-Control: public, max-age=31536000, immutable. Eftersom IPFS-innehåll är innehållsadresserat producerar samma CID med samma parametrar alltid samma utdata, så webbläsare och CDN:er kan cacha svar på obestämd tid.

Cachade transformationer lagras i S3 indexerade efter den fullständiga parameteruppsättningen (cid, w, h, format, quality, fit). Efterföljande begäranden med samma parametrar returnerar en 302-redirect till CloudFront-cachen (https://ipfs.ninja/image-cache/...) i stället för att köra om transformationen. Olika parameterkombinationer producerar olika cacheposter.

Tillgänglighet

Bildoptimering är tillgänglig på alla planer, inklusive den gratis Dharma-planen.