Optimalizace obrázků

Transformujte a optimalizujte obrázky obsluhované z IPFS za běhu pomocí dotazovacích parametrů. Toto je veřejný endpoint, který nevyžaduje autentizaci.

Optimize Image

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

Vrací obrázek s daným CID transformovaný podle poskytnutých dotazovacích parametrů. Pokud nejsou zadány žádné parametry transformace, požadavek je přesměrován pomocí 302 na původní obrázek na IPFS bráně.

Parametry cesty

Parametr	Typ	Povinné	Popis
cid	string	Ano	IPFS identifikátor obsahu obrázku.

Dotazovací parametry

Parametr	Typ	Výchozí	Popis
w	integer	—	Šířka výstupu v pixelech. Rozsah: 1–4096. Hodnoty ≤ 0 nebo nečíselné jsou ignorovány.
h	integer	—	Výška výstupu v pixelech. Rozsah: 1–4096. Hodnoty ≤ 0 nebo nečíselné jsou ignorovány.
format	string	—	Výstupní formát: webp, jpeg, png nebo avif. Rozlišuje malá a velká písmena (malá písmena). Neznámé hodnoty jsou ignorovány.
quality	integer	80	Kvalita komprese, 1–100. Platí pouze pro webp, jpeg a avif. png je bezztrátový a tuto hodnotu ignoruje.
fit	string	cover	Jak má obrázek zapadnout do rozměrů: cover, contain, fill, inside nebo outside.

Poznámka: parametr je quality, nikoli q. Běžné zkratkové aliasy (q, width, height, fmt) nejsou rozpoznány.

Požadavek, který neobsahuje žádný z w, h ani format, je považován za prázdnou operaci a je přesměrován pomocí 302 na původní obrázek. Samotné quality a fit transformaci nespustí.

Režimy zarovnání

Režim	Chování
cover	Ořízne tak, aby pokryl oba rozměry (výchozí).
contain	Vejde se do obou rozměrů při zachování poměru stran. Může zanechat prázdný prostor (průhledný nebo černý podle formátu).
fill	Roztáhne tak, aby přesně vyplnil oba rozměry. Může obrázek zkreslit.
inside	Jako contain, ale pouze zmenšuje, nikdy nezvětšuje.
outside	Jako cover, ale pouze zmenšuje, nikdy nezvětšuje.

Zvětšování

Transformátor nikdy nezvětší obrázek nad jeho zdrojové rozměry. Pokud požadujete w=2000 pro zdroj široký 1200px, výstup bude široký 1200px. To platí pro všechny režimy fit.

Odpověď

Status	Kdy	Tělo
200	Transformace byla provedena při tomto požadavku.	Binární bajty obrázku. Content-Type odpovídá požadovanému formátu.
302	Nebyly zadány žádné parametry transformace, nebo je již dříve transformovaný výsledek v cache.	Hlavička Location směřuje na původní obrázek nebo na cachovaný výsledek na https://ipfs.ninja/image-cache/....
400	Chybí parametr cesty cid.	{ "error": "cid required" }
404	CID nebyl na bráně nalezen.	{ "error": "CID not found" }
500	Neočekávaná chyba (poškozený obrázek, selhání transformace atd.).	{ "error": "<message>" }

Všechny odpovědi 200 a 302-cache jsou obsluhovány s hlavičkou Cache-Control: public, max-age=31536000, immutable. Viz Cachování níže.

Příklady požadavků

Změna velikosti na šířku 400px, konverze do WebP:

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

Změna velikosti a oříznutí na náhled 200×200 jako JPEG s 60% kvalitou:

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

Čtvercový náhled s letterboxingem místo oříznutí:

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

Pouze konverze formátu, bez změny velikosti (užitečné pro poskytování AVIF/WebP verzí starších JPEG):

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

Omezení maximální šířky bez vynucení výšky (zachovává poměr stran):

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

Použití v HTML

Odkazujte na optimalizované obrázky přímo v tazích img:

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

Poskytujte různé velikosti pomocí 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ávání moderního formátu pomocí <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žití s Next.js

Jako vlastní loader pro 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}
/>;

Cachování

Odpovědi jsou obsluhovány s hlavičkou Cache-Control: public, max-age=31536000, immutable. Protože obsah IPFS je adresován obsahem, stejné CID se stejnými parametry vždy produkuje stejný výstup, takže prohlížeče a CDN mohou odpovědi cachovat neomezeně dlouho.

Cachované transformace jsou uloženy v S3 s klíčem podle úplné sady parametrů (cid, w, h, format, quality, fit). Následné požadavky se stejnými parametry vrací přesměrování 302 na cache za CloudFrontem (https://ipfs.ninja/image-cache/...) místo opakovaného spuštění transformace. Různé kombinace parametrů produkují různé záznamy v cache.

Dostupnost

Optimalizace obrázků je dostupná u všech tarifů, včetně bezplatného tarifu Dharma.