Bildeoptimalisering

Transformer og optimaliser bilder som serveres fra IPFS on-the-fly ved hjelp av spørringsparametere. Dette er et offentlig endepunkt som ikke krever autentisering.

Optimera bild

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

Returnerer bildet med oppgitt CID, transformert i henhold til de oppgitte spørringsparameterne. Hvis ingen transformasjonsparametere oppgis, omdirigeres forespørselen med en 302-redirect til originalbildet på IPFS-gatewayen.

Path parameters

Parameter	Type	Required	Description
cid	string	Ja	Bildets IPFS content identifier.

Query parameters

Parameter	Type	Default	Description
w	integer	—	Utdatabredde i piksler. Område: 1–4096. Verdier ≤ 0 eller ikke-numeriske ignoreres.
h	integer	—	Utdatahøyde i piksler. Område: 1–4096. Verdier ≤ 0 eller ikke-numeriske ignoreres.
format	string	—	Utdataformat: webp, jpeg, png eller avif. Skiller mellom store og små bokstaver (små). Ukjente verdier ignoreres.
quality	integer	80	Komprimeringskvalitet, 1–100. Gjelder kun for webp, jpeg og avif. png er tapsfritt og ignorerer denne.
fit	string	cover	Hvordan bildet skal passe dimensjonene: cover, contain, fill, inside eller outside.

Merk: parameteren heter quality, ikke q. Vanlige forkortelser (q, width, height, fmt) gjenkjennes ikke.

En forespørsel som ikke inneholder noen av w, h eller format, behandles som en no-op og omdirigeres med en 302-redirect til originalbildet. quality og fit alene utløser ingen transformasjon.

Fit modes

Mode	Behavior
cover	Beskjær for å dekke begge dimensjonene (standard).
contain	Tilpass innenfor begge dimensjonene, behold sideforholdet. Kan etterlate tomt rom (transparent eller svart, avhengig av format).
fill	Strekk for å fylle begge dimensjonene nøyaktig. Kan forvrenge bildet.
inside	Som contain, men skalerer kun ned, aldri opp.
outside	Som cover, men skalerer kun ned, aldri opp.

Oppskalering

Transformeren forstørrer aldri et bilde utover dets kildedimensjoner. Hvis du ber om w=2000 for en kilde på 1200px bred, blir utdataen 1200px bred. Dette gjelder alle fit-moduser.

Response

Status	When	Body
200	Transformasjon produsert ved denne forespørselen.	Binære bildedata. Content-Type matcher det forespurte formatet.
302	Ingen transformasjonsparametere oppgitt, eller et tidligere transformert resultat er allerede bufret.	Location-header peker på originalbildet eller det bufrede resultatet på https://ipfs.ninja/image-cache/....
400	cid-stiparameter mangler.	{ "error": "cid required" }
404	CID ble ikke funnet på gatewayen.	{ "error": "CID not found" }
500	Uventet feil (ødelagt bilde, transformasjonsfeil osv.).	{ "error": "<message>" }

Alle 200- og 302-cachesvar leveres med Cache-Control: public, max-age=31536000, immutable. Se Cachning nedenfor.

Example requests

Endre størrelse til 400px bred, konverter til WebP:

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

Endre størrelse og beskjær til 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 stedet for beskjæring:

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

Konverter kun format, ingen størrelsesendring (nyttig for å levere AVIF/WebP-versjoner av eldre JPEG-er):

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

Begrens maksimal bredde uten å tvinge høyde (bevarer sideforholdet):

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

Using in HTML

Referer til optimaliserte bilder direkte i img-tagger:

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

Server forskjellige størrelser 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="Responsive IPFS image"
/>

Moderne formatforhandling 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");
}

Bruk med Next.js

Som tilpasset loader for 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}
/>;

Cachning

Svar leveres med Cache-Control: public, max-age=31536000, immutable. Siden IPFS-innhold er innholdsadressert, produserer samme CID med samme parametere alltid samme utdata, slik at nettlesere og CDN-er kan cache svar på ubestemt tid.

Bufrede transformasjoner lagres i S3 indeksert etter hele parametersettet (cid, w, h, format, quality, fit). Etterfølgende forespørsler med samme parametere returnerer en 302-redirect til CloudFront-cachen (https://ipfs.ninja/image-cache/...) i stedet for å kjøre transformasjonen på nytt. Ulike parameterkombinasjoner produserer ulike cache-oppføringer.

Tillganglighet

Bildeoptimalisering er tilgjengelig på alle planer, inkludert den gratis Dharma-planen.