Image Optimization

Трансформуйте та оптимізуйте зображення, що подаються з 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"

Квадратна мініатюра з леттербоксингом замість обрізки:

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.