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

Трансформирайте и оптимизирайте изображения, обслужвани от IPFS, в реално време чрез параметри в заявката. Това е публична крайна точка, която не изисква удостоверяване. За качване на изходните изображения вижте качване на файлове; за основите на адресирането по съдържание вижте адресиране по съдържание в IPFS.

Преоразмерете, конвертирайте и изрежете IPFS изображение (GET /image/:cid)

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.

Отговор

Статус	Кога	Тяло
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 могат да кешират отговорите безсрочно.

Кешираните трансформации се съхраняват в обектно хранилище, индексирано по пълния набор от параметри (cid, w, h, format, quality, fit). Последващите заявки със същите параметри връщат пренасочване 302 към кеширания резултат зад CDN мрежата (https://ipfs.ninja/image-cache/...), вместо да изпълняват трансформацията отново. Различните комбинации от параметри водят до различни кеш записи.

Достъпност

Оптимизацията на изображения е достъпна във всички планове, включително безплатния план Dharma.