Оптимизација слика

Трансформишите и оптимизујте слике послужене са IPFS-а у ходу помоћу параметара упита. Ово је јавна крајња тачка која не захтева аутентификацију.

Optimize Image

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

Враћа слику са датим CID-ом, трансформисану према достављеним параметрима упита. Ако нису наведени параметри трансформације, захтев се преусмерава са 302 на изворну слику на IPFS пролазу.

Параметри путање

Параметар	Тип	Обавезно	Опис
cid	string	Да	IPFS идентификатор садржаја слике.

Параметри упита

Параметар	Тип	Подразумевано	Опис
w	integer	—	Излазна ширина у пикселима. Опсег: 1–4096. Вредности ≤ 0 или небројчане се игноришу.
h	integer	—	Излазна висина у пикселима. Опсег: 1–4096. Вредности ≤ 0 или небројчане се игноришу.
format	string	—	Излазни формат: webp, jpeg, png или avif. Разликује велика и мала слова (мала слова). Непознате вредности се игноришу.
quality	integer	80	Квалитет компресије, 1–100. Примењује се само на webp, jpeg и avif. png је без губитака и игнорише ово.
fit	string	cover	Како слика треба да се уклопи у димензије: cover, contain, fill, inside или outside.

Напомена: параметар је quality, не q. Уобичајени скраћени алијаси (q, width, height, fmt) нису препознати.

Захтев који не наводи ниједан од w, h или format третира се као без радње и преусмерава се са 302 на изворну слику. Сами quality и fit не покрећу трансформацију.

Режими уклапања

Режим	Понашање
cover	Исече да покрије обе димензије (подразумевано).
contain	Стане у обе димензије уз очување односа страница. Може оставити празан простор (провидан или црн зависно од формата).
fill	Растеже за тачно попуњавање обе димензије. Може искривити слику.
inside	Као contain, али само смањује, никад не повећава.
outside	Као cover, али само смањује, никад не повећава.

Повећавање

Трансформатор никада не повећава слику изнад њених изворних димензија. Ако захтевате w=2000 за извор ширине 1200px, излаз ће бити широк 1200px. Ово се односи на све fit режиме.

Одговор

Status	Када	Body
200	Трансформација је извршена на овом захтеву.	Бинарни бајтови слике. Content-Type одговара захтеваном формату.
302	Нису наведени параметри трансформације или је претходно трансформисани резултат већ кеширан.	Заглавље Location показује на изворну слику или на кеширани резултат на https://ipfs.ninja/image-cache/....
400	Недостаје параметар путање cid.	{ "error": "cid required" }
404	CID није пронађен на пролазу.	{ "error": "CID not found" }
500	Неочекивана грешка (оштећена слика, неуспех трансформације итд.).	{ "error": "<message>" }

Сви одговори 200 и 302-кеш послужују се са заглављем Cache-Control: public, max-age=31536000, immutable. Погледајте Кеширање испод.

Примери захтева

Промена величине на 400px ширине, конверзија у WebP:

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

Промена величине и исецање на сличицу 200×200 као JPEG са 60% квалитета:

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

Квадратна сличица са letterboxing-ом уместо исецања:

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

Само конверзија формата, без промене величине (корисно за послуживање AVIF/WebP верзија старијих JPEG-ова):

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

Ограничавање максималне ширине без наметања висине (чува однос страница):

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

Коришћење у HTML-у

Референцирајте оптимизоване слике директно у img ознакама:

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

Послужујте различите величине помоћу 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"
/>

Преговарање модерног формата помоћу <picture> (AVIF → WebP → JPEG резерва):

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

Коришћење са Next.js

Као прилагођени loader за 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}
/>;

Кеширање

Одговори се послужују са заглављем Cache-Control: public, max-age=31536000, immutable. Пошто је садржај IPFS-а адресиран садржајем, исти CID са истим параметрима увек производи исти излаз, тако да прегледачи и CDN-ови могу да кеширају одговоре неограничено дуго.

Кеширане трансформације се чувају у S3 са кључем по комплетном скупу параметара (cid, w, h, format, quality, fit). Накнадни захтеви са истим параметрима враћају преусмеравање 302 на кеш иза CloudFront-а (https://ipfs.ninja/image-cache/...) уместо поновног покретања трансформације. Различите комбинације параметара производе различите уносе у кешу.

Доступност

Оптимизација слика је доступна на свим плановима, укључујући бесплатни Dharma план.