Image Optimization

Przekształcaj i optymalizuj obrazy serwowane z IPFS w locie za pomocą parametrów zapytania. Jest to publiczny punkt końcowy, który nie wymaga uwierzytelniania.

Optimize Image

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

Zwraca obraz o podanym CID, przekształcony zgodnie z dostarczonymi parametrami zapytania. Jeśli nie zostaną podane żadne parametry transformacji, żądanie wykonuje przekierowanie 302 do oryginalnego obrazu w bramie IPFS.

Parametry ścieżki

Parametr	Typ	Wymagany	Opis
cid	string	Tak	Identyfikator zawartości IPFS obrazu.

Parametry zapytania

Parametr	Typ	Domyślnie	Opis
w	integer	—	Szerokość wyjściowa w pikselach. Zakres: 1–4096. Wartości ≤ 0 lub nieliczbowe są ignorowane.
h	integer	—	Wysokość wyjściowa w pikselach. Zakres: 1–4096. Wartości ≤ 0 lub nieliczbowe są ignorowane.
format	string	—	Format wyjściowy: webp, jpeg, png lub avif. Wrażliwy na wielkość liter (małe litery). Nieznane wartości są ignorowane.
quality	integer	80	Jakość kompresji, 1–100. Stosuje się tylko do webp, jpeg i avif. png jest bezstratny i ignoruje tę wartość.
fit	string	cover	Sposób dopasowania obrazu do wymiarów: cover, contain, fill, inside lub outside.

Uwaga: parametr nazywa się quality, nie q. Popularne skrócone aliasy (q, width, height, fmt) nie są rozpoznawane.

Żądanie, które nie podaje żadnego z w, h ani format, traktowane jest jako brak operacji i wykonuje przekierowanie 302 do oryginalnego obrazu. Same quality i fit nie wyzwalają transformacji.

Tryby dopasowania

Tryb	Zachowanie
cover	Przycina, aby pokryć oba wymiary (domyślnie).
contain	Mieści się w obu wymiarach, zachowując proporcje. Może pozostawić puste miejsce (przezroczyste lub czarne, w zależności od formatu).
fill	Rozciąga, aby dokładnie wypełnić oba wymiary. Może zniekształcić obraz.
inside	Jak contain, ale tylko zmniejsza, nigdy nie powiększa.
outside	Jak cover, ale tylko zmniejsza, nigdy nie powiększa.

Powiększanie

Transformator nigdy nie powiększa obrazu poza jego wymiary źródłowe. Jeśli zażądasz w=2000 dla źródła o szerokości 1200px, wyjście będzie miało szerokość 1200px. Dotyczy to wszystkich trybów fit.

Odpowiedź

Status	Kiedy	Body
200	Transformacja została wykonana w tym żądaniu.	Bajty binarne obrazu. Content-Type odpowiada żądanemu formatowi.
302	Nie podano parametrów transformacji lub wcześniej przekształcony wynik jest już w cache.	Nagłówek Location wskazuje na oryginalny obraz lub na buforowany wynik pod https://ipfs.ninja/image-cache/....
400	Brak parametru ścieżki cid.	{ "error": "cid required" }
404	Nie znaleziono CID w bramie.	{ "error": "CID not found" }
500	Nieoczekiwany błąd (uszkodzony obraz, niepowodzenie transformacji itp.).	{ "error": "<message>" }

Wszystkie odpowiedzi 200 i 302-cache są serwowane z nagłówkiem Cache-Control: public, max-age=31536000, immutable. Zobacz Buforowanie poniżej.

Przykładowe żądania

Zmiana rozmiaru do szerokości 400px, konwersja do WebP:

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

Zmiana rozmiaru i przycięcie do miniatury 200×200 w formacie JPEG z jakością 60%:

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

Kwadratowa miniatura z letterboxingiem zamiast przycięcia:

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

Tylko konwersja formatu, bez zmiany rozmiaru (przydatne do serwowania wersji AVIF/WebP starszych plików JPEG):

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

Ograniczenie maksymalnej szerokości bez wymuszania wysokości (zachowuje proporcje):

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

Użycie w HTML

Odwołuj się do zoptymalizowanych obrazów bezpośrednio w tagach img:

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

Serwuj różne rozmiary za 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"
/>

Negocjacja nowoczesnego formatu z <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");
}

Użycie z Next.js

Jako niestandardowy loader dla 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}
/>;

Buforowanie

Odpowiedzi serwowane są z nagłówkiem Cache-Control: public, max-age=31536000, immutable. Ponieważ zawartość IPFS jest adresowana zawartością, ten sam CID z tymi samymi parametrami zawsze daje ten sam wynik, więc przeglądarki i CDN mogą buforować odpowiedzi bezterminowo.

Buforowane transformacje są przechowywane w S3 z kluczem opartym na pełnym zestawie parametrów (cid, w, h, format, quality, fit). Kolejne żądania z tymi samymi parametrami zwracają przekierowanie 302 do bufora za CloudFront (https://ipfs.ninja/image-cache/...) zamiast ponownego uruchamiania transformacji. Różne kombinacje parametrów dają różne wpisy w cache.

Dostępność

Optymalizacja obrazów jest dostępna we wszystkich planach, w tym w bezpłatnym planie Dharma.