Optimizacija slika

Transformirajte i optimizirajte slike posluživane s IPFS-a u hodu pomoću upitnih parametara. Ovo je javna krajnja točka koja ne zahtijeva autentifikaciju.

Optimize Image

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

Vraća sliku s navedenim CID-om, transformiranu prema dostavljenim upitnim parametrima. Ako nisu navedeni parametri transformacije, zahtjev se preusmjerava s 302 na izvornu sliku na IPFS pristupniku.

Parametri staze

Parametar	Tip	Obavezno	Opis
cid	string	Da	IPFS identifikator sadržaja slike.

Upitni parametri

Parametar	Tip	Zadano	Opis
w	integer	—	Izlazna širina u pikselima. Raspon: 1–4096. Vrijednosti ≤ 0 ili nebrojčane se ignoriraju.
h	integer	—	Izlazna visina u pikselima. Raspon: 1–4096. Vrijednosti ≤ 0 ili nebrojčane se ignoriraju.
format	string	—	Izlazni format: webp, jpeg, png ili avif. Razlikuje velika i mala slova (mala slova). Nepoznate vrijednosti se ignoriraju.
quality	integer	80	Kvaliteta kompresije, 1–100. Primjenjuje se samo na webp, jpeg i avif. png je bez gubitaka i ignorira ovo.
fit	string	cover	Kako slika treba pristajati dimenzijama: cover, contain, fill, inside ili outside.

Napomena: parametar je quality, ne q. Uobičajeni skraćeni aliasi (q, width, height, fmt) nisu prepoznati.

Zahtjev koji ne navodi nijedan od w, h ili format tretira se kao bez radnje i preusmjerava se s 302 na izvornu sliku. Sami quality i fit ne pokreću transformaciju.

Načini uklapanja

Način	Ponašanje
cover	Obreže za pokrivanje obje dimenzije (zadano).
contain	Stane unutar obje dimenzije uz očuvanje omjera. Može ostaviti prazan prostor (proziran ili crn ovisno o formatu).
fill	Razvuče za točno popunjavanje obje dimenzije. Može iskriviti sliku.
inside	Kao contain, ali samo smanjuje, nikad ne povećava.
outside	Kao cover, ali samo smanjuje, nikad ne povećava.

Povećavanje

Transformator nikada ne povećava sliku iznad njezinih izvornih dimenzija. Ako zatražite w=2000 za izvor širine 1200px, izlaz će biti širok 1200px. Ovo se odnosi na sve fit načine.

Odgovor

Status	Kada	Tijelo
200	Transformacija je proizvedena na ovom zahtjevu.	Binarni bajtovi slike. Content-Type odgovara zatraženom formatu.
302	Nisu navedeni parametri transformacije ili je prethodno transformirani rezultat već u cacheu.	Zaglavlje Location upućuje na izvornu sliku ili na cachirani rezultat na https://ipfs.ninja/image-cache/....
400	Nedostaje parametar staze cid.	{ "error": "cid required" }
404	CID nije pronađen na pristupniku.	{ "error": "CID not found" }
500	Neočekivana pogreška (oštećena slika, neuspjeh transformacije itd.).	{ "error": "<message>" }

Svi odgovori 200 i 302-cache poslužuju se sa zaglavljem Cache-Control: public, max-age=31536000, immutable. Pogledajte Cachiranje u nastavku.

Primjeri zahtjeva

Promjena veličine na 400px širine, konverzija u WebP:

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

Promjena veličine i obrezivanje na sličicu 200×200 kao JPEG s 60% kvalitetom:

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

Kvadratna sličica s letterboxingom umjesto obrezivanja:

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

Samo konverzija formata, bez promjene veličine (korisno za posluživanje AVIF/WebP verzija starijih JPEG-ova):

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

Ograničavanje maksimalne širine bez nametanja visine (čuva omjer):

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

Korištenje u HTML-u

Referencirajte optimizirane slike izravno u img oznakama:

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

Posluživanje različitih veličina pomoću 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"
/>

Pregovaranje modernog formata s <picture> (AVIF → WebP → JPEG zamjena):

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

Korištenje s Next.js

Kao prilagođeni loader za 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}
/>;

Cachiranje

Odgovori se poslužuju sa zaglavljem Cache-Control: public, max-age=31536000, immutable. Budući da je sadržaj IPFS-a adresiran sadržajem, isti CID s istim parametrima uvijek proizvodi isti izlaz, pa preglednici i CDN-ovi mogu cachirati odgovore neograničeno dugo.

Cachirane transformacije pohranjuju se u S3 s ključem po cijelom skupu parametara (cid, w, h, format, quality, fit). Naknadni zahtjevi s istim parametrima vraćaju preusmjeravanje 302 na cache iza CloudFronta (https://ipfs.ninja/image-cache/...) umjesto ponovnog pokretanja transformacije. Različite kombinacije parametara proizvode različite unose u cacheu.

Dostupnost

Optimizacija slika dostupna je na svim planovima, uključujući besplatni Dharma plan.