Billedoptimering

Transformer og optimer billeder, der serveres fra IPFS, on-the-fly ved hjælp af forespørgselsparametre. Dette er et offentligt endpoint, der ikke kræver autentificering.

Optimera bild

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

Returnerer billedet med det angivne CID, transformeret i henhold til de angivne forespørgselsparametre. Hvis ingen transformationsparametre angives, omdirigeres anmodningen med en 302-redirect til det originale billede på IPFS-gatewayen.

Path parameters

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

Query parameters

Parameter	Type	Default	Description
w	integer	—	Outputbredde i pixel. Område: 1–4096. Værdier ≤ 0 eller ikke-numeriske ignoreres.
h	integer	—	Outputhøjde i pixel. Område: 1–4096. Værdier ≤ 0 eller ikke-numeriske ignoreres.
format	string	—	Outputformat: webp, jpeg, png eller avif. Versalfølsomt (små bogstaver). Ukendte værdier ignoreres.
quality	integer	80	Komprimeringskvalitet, 1–100. Gælder kun for webp, jpeg og avif. png er tabsfri og ignorerer denne.
fit	string	cover	Hvordan billedet skal passe til dimensionerne: cover, contain, fill, inside eller outside.

Bemærk: parameteren hedder quality, ikke q. Almindelige forkortelser (q, width, height, fmt) genkendes ikke.

En anmodning, der hverken indeholder w, h eller format, behandles som en no-op og omdirigeres med en 302-redirect til det originale billede. quality og fit alene udløser ikke en transformation.

Fit modes

Mode	Behavior
cover	Beskær for at dække begge dimensioner (standard).
contain	Pas inden for begge dimensioner, bevar billedforholdet. Kan efterlade tomt rum (transparent eller sort afhængigt af format).
fill	Stræk for at udfylde begge dimensioner præcist. Kan forvrænge billedet.
inside	Som contain, men skalerer kun ned, aldrig op.
outside	Som cover, men skalerer kun ned, aldrig op.

Opskalering

Transformeren forstørrer aldrig et billede ud over dets kildedimensioner. Hvis du anmoder om w=2000 for en kilde på 1200px bred, vil outputtet være 1200px bredt. Dette gælder for alle fit-tilstande.

Response

Status	When	Body
200	Transformation produceret ved denne anmodning.	Binære billeddata. Content-Type matcher det ønskede format.
302	Ingen transformationsparametre angivet, eller et tidligere transformeret resultat er allerede cachet.	Location-header peger på det originale billede eller det cachede resultat på https://ipfs.ninja/image-cache/....
400	cid-stiparameter mangler.	{ "error": "cid required" }
404	CID ikke fundet på gatewayen.	{ "error": "CID not found" }
500	Uventet fejl (beskadiget billede, transformationsfejl osv.).	{ "error": "<message>" }

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

Example requests

Ændr størrelse til 400px bred, konverter til WebP:

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

Ændr størrelse og beskær til 200×200 miniature som JPEG med 60% kvalitet:

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

Kvadratisk miniature med letterboxing i stedet for beskæring:

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

Konverter kun format, ingen størrelsesændring (nyttigt til at servere AVIF/WebP-versioner af gamle JPEGs):

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

Begræns maksimal bredde uden at tvinge højde (bevarer billedforholdet):

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

Using in HTML

Henvis til optimerede billeder direkte i img-tags:

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

Server forskellige 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");
}

Brug med Next.js

Som brugerdefineret loader til 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. Da IPFS-indhold er content-addressed, producerer det samme CID med de samme parametre altid det samme output, så browsere og CDN'er kan cache svar i ubegrænset tid.

Cachede transformationer gemmes i S3 indekseret efter det fulde parametersæt (cid, w, h, format, quality, fit). Efterfølgende anmodninger med de samme parametre returnerer en 302-redirect til CloudFront-cachen (https://ipfs.ninja/image-cache/...) i stedet for at køre transformationen igen. Forskellige parameterkombinationer producerer forskellige cache-poster.

Tillganglighet

Image optimization er tilgængelig på alle planer, inklusive den gratis Dharma-plan.