Képoptimalizálás

Alakítsa át és optimalizálja az IPFS-ről kiszolgált képeket menet közben lekérdezési paraméterek segítségével. Ez egy nyilvános végpont, amely nem igényel hitelesítést.

Optimize Image

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

Visszaadja a megadott CID-hez tartozó képet, a megadott lekérdezési paraméterek szerint átalakítva. Ha nincsenek átalakítási paraméterek megadva, a kérés 302-vel átirányít az eredeti képre az IPFS átjárón.

Útvonal paraméterek

Paraméter	Típus	Kötelező	Leírás
cid	string	Igen	A kép IPFS tartalom-azonosítója.

Lekérdezési paraméterek

Paraméter	Típus	Alapértelmezett	Leírás
w	integer	—	Kimeneti szélesség pixelben. Tartomány: 1–4096. A ≤ 0 vagy nem numerikus értékeket figyelmen kívül hagyja.
h	integer	—	Kimeneti magasság pixelben. Tartomány: 1–4096. A ≤ 0 vagy nem numerikus értékeket figyelmen kívül hagyja.
format	string	—	Kimeneti formátum: webp, jpeg, png vagy avif. Kis- és nagybetű érzékeny (kisbetű). Az ismeretlen értékeket figyelmen kívül hagyja.
quality	integer	80	Tömörítési minőség, 1–100. Csak a webp, jpeg és avif formátumokra vonatkozik. A png veszteségmentes és figyelmen kívül hagyja ezt.
fit	string	cover	Hogyan illeszkedjen a kép a méretekhez: cover, contain, fill, inside vagy outside.

Megjegyzés: a paraméter quality, nem q. A gyakori rövidített álnevek (q, width, height, fmt) nem felismerhetők.

Az olyan kérés, amely nem ad meg sem w, sem h, sem format paramétert, művelet nélküliként kezelődik, és 302-vel átirányít az eredeti képre. A quality és fit önmagukban nem indítanak átalakítást.

Illeszkedési módok

Mód	Viselkedés
cover	Vágás úgy, hogy mindkét méretet lefedje (alapértelmezett).
contain	Beilleszkedik mindkét méretbe, megőrzi az oldalarányt. Üres helyet hagyhat (átlátszó vagy fekete a formátumtól függően).
fill	Pontosan kitölti mindkét méretet nyújtással. Torzíthatja a képet.
inside	Mint a contain, de csak kicsinyít, soha nem nagyít.
outside	Mint a cover, de csak kicsinyít, soha nem nagyít.

Felskálázás

Az átalakító soha nem nagyítja a képet a forrásméreten túl. Ha w=2000-t kér egy 1200px széles forráshoz, a kimenet 1200px széles lesz. Ez minden fit módra érvényes.

Válasz

Status	Mikor	Body
200	Átalakítás történt erre a kérésre.	Bináris képbájtok. A Content-Type megegyezik a kért formátummal.
302	Nincs átalakítási paraméter megadva, vagy egy korábban átalakított eredmény már gyorsítótárazva van.	A Location fejléc az eredeti képre vagy a gyorsítótárazott eredményre mutat a https://ipfs.ninja/image-cache/... címen.
400	Hiányzik a cid útvonal paraméter.	{ "error": "cid required" }
404	A CID nem található az átjárón.	{ "error": "CID not found" }
500	Váratlan hiba (sérült kép, sikertelen átalakítás stb.).	{ "error": "<message>" }

Minden 200 és 302-gyorsítótár válasz a Cache-Control: public, max-age=31536000, immutable fejléccel kerül kiszolgálásra. Lásd a Gyorsítótárazás szakaszt alább.

Példa kérések

Átméretezés 400px szélességre, konvertálás WebP-re:

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

Átméretezés és körbevágás 200×200-as bélyegképre JPEG-ként, 60%-os minőséggel:

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

Négyzet alakú bélyegkép letterboxinggal körbevágás helyett:

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

Csak formátumkonverzió, átméretezés nélkül (hasznos régi JPEG-ek AVIF/WebP verzióinak kiszolgálásához):

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

Maximális szélesség korlátozása magasság kényszerítése nélkül (megőrzi az oldalarányt):

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

Használat HTML-ben

Hivatkozzon optimalizált képekre közvetlenül img címkékben:

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

Különböző méretek kiszolgálása srcset-tel:

<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"
/>

Modern formátumegyeztetés <picture>-rel (AVIF → WebP → JPEG tartalék):

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

Használat Next.js-szel

Egyéni loaderként a next/image-hez:

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

Gyorsítótárazás

A válaszok a Cache-Control: public, max-age=31536000, immutable fejléccel kerülnek kiszolgálásra. Mivel az IPFS tartalom tartalom-címzett, ugyanaz a CID ugyanazokkal a paraméterekkel mindig ugyanazt a kimenetet eredményezi, így a böngészők és CDN-ek a válaszokat korlátlanul gyorsítótárazhatják.

A gyorsítótárazott átalakítások az S3-ban vannak tárolva, a teljes paraméterkészlettel kulcsolva (cid, w, h, format, quality, fit). Az ugyanazokkal a paraméterekkel érkező későbbi kérések 302 átirányítást adnak vissza a CloudFront mögötti gyorsítótárhoz (https://ipfs.ninja/image-cache/...), ahelyett, hogy újra futtatnák az átalakítást. A különböző paraméterkombinációk különböző gyorsítótár-bejegyzéseket eredményeznek.

Elérhetőség

A képoptimalizálás minden csomagban elérhető, beleértve az ingyenes Dharma csomagot is.