Оптимизация изображений

Трансформируйте и оптимизируйте изображения из IPFS на лету с помощью параметров запроса. Это публичная конечная точка, не требующая аутентификации.

Оптимизировать изображение

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.