Optimalizácia obrázkov

Transformujte a optimalizujte obrázky obsluhované z IPFS za behu pomocou dotazovacích parametrov. Toto je verejný endpoint, ktorý nevyžaduje autentifikáciu.

Optimize Image

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

Vracia obrázok s daným CID transformovaný podľa poskytnutých dotazovacích parametrov. Ak nie sú zadané žiadne parametre transformácie, požiadavka je presmerovaná pomocou 302 na pôvodný obrázok na IPFS bráne.

Parametre cesty

Parameter	Typ	Povinné	Popis
cid	string	Áno	IPFS identifikátor obsahu obrázka.

Dotazovacie parametre

Parameter	Typ	Predvolené	Popis
w	integer	—	Šírka výstupu v pixeloch. Rozsah: 1–4096. Hodnoty ≤ 0 alebo nečíselné sú ignorované.
h	integer	—	Výška výstupu v pixeloch. Rozsah: 1–4096. Hodnoty ≤ 0 alebo nečíselné sú ignorované.
format	string	—	Výstupný formát: webp, jpeg, png alebo avif. Rozlišuje veľkosť písmen (malé písmená). Neznáme hodnoty sú ignorované.
quality	integer	80	Kvalita kompresie, 1–100. Platí iba pre webp, jpeg a avif. png je bezstratový a túto hodnotu ignoruje.
fit	string	cover	Ako má obrázok zapadnúť do rozmerov: cover, contain, fill, inside alebo outside.

Poznámka: parameter sa nazýva quality, nie q. Bežné skratkové aliasy (q, width, height, fmt) nie sú rozpoznané.

Požiadavka, ktorá neobsahuje žiadny z w, h ani format, je považovaná za prázdnu operáciu a je presmerovaná pomocou 302 na pôvodný obrázok. Samotné quality a fit transformáciu nespustia.

Režimy zarovnania

Režim	Správanie
cover	Oreže tak, aby pokryl obe rozmery (predvolené).
contain	Zmestí sa do oboch rozmerov so zachovaním pomeru strán. Môže nechať prázdny priestor (priehľadný alebo čierny podľa formátu).
fill	Roztiahne tak, aby presne vyplnil obe rozmery. Môže obrázok skresliť.
inside	Ako contain, ale iba zmenšuje, nikdy nezväčšuje.
outside	Ako cover, ale iba zmenšuje, nikdy nezväčšuje.

Zväčšovanie

Transformátor nikdy nezväčší obrázok nad jeho zdrojové rozmery. Ak požadujete w=2000 pre zdroj široký 1200px, výstup bude široký 1200px. Toto platí pre všetky režimy fit.

Odpoveď

Status	Kedy	Telo
200	Transformácia bola vykonaná pri tejto požiadavke.	Binárne bajty obrázka. Content-Type zodpovedá požadovanému formátu.
302	Neboli zadané žiadne parametre transformácie alebo je už predtým transformovaný výsledok v cache.	Hlavička Location smeruje na pôvodný obrázok alebo na cachovaný výsledok na https://ipfs.ninja/image-cache/....
400	Chýba parameter cesty cid.	{ "error": "cid required" }
404	CID nebol na bráne nájdený.	{ "error": "CID not found" }
500	Neočakávaná chyba (poškodený obrázok, zlyhanie transformácie atď.).	{ "error": "<message>" }

Všetky odpovede 200 a 302-cache sú obsluhované s hlavičkou Cache-Control: public, max-age=31536000, immutable. Pozri Cachovanie nižšie.

Príklady požiadaviek

Zmena veľkosti na šírku 400px, konverzia do WebP:

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

Zmena veľkosti a orezanie na náhľad 200×200 ako JPEG so 60% kvalitou:

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

Štvorcový náhľad s letterboxingom namiesto orezania:

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

Iba konverzia formátu, bez zmeny veľkosti (užitočné na poskytovanie AVIF/WebP verzií starších JPEG):

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

Obmedzenie maximálnej šírky bez vynútenia výšky (zachováva pomer strán):

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

Použitie v HTML

Odkazujte na optimalizované obrázky priamo v tagoch img:

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

Poskytujte rôzne veľkosti pomocou 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"
/>

Vyjednávanie moderného formátu pomocou <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");
}

Použitie s Next.js

Ako vlastný loader pre 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}
/>;

Cachovanie

Odpovede sú obsluhované s hlavičkou Cache-Control: public, max-age=31536000, immutable. Keďže obsah IPFS je adresovaný obsahom, rovnaké CID s rovnakými parametrami vždy produkuje rovnaký výstup, takže prehliadače a CDN môžu odpovede cachovať neobmedzene dlho.

Cachované transformácie sú uložené v S3 s kľúčom podľa úplnej sady parametrov (cid, w, h, format, quality, fit). Následné požiadavky s rovnakými parametrami vracajú presmerovanie 302 na cache za CloudFrontom (https://ipfs.ninja/image-cache/...) namiesto opakovaného spustenia transformácie. Rôzne kombinácie parametrov produkujú rôzne záznamy v cache.

Dostupnosť

Optimalizácia obrázkov je dostupná vo všetkých plánoch, vrátane bezplatného plánu Dharma.