Optimizacija slik

Pretvorite in optimizirajte slike, postrežene iz IPFS, sproti s pomočjo poizvedbenih parametrov. To je javna končna točka, ki ne zahteva avtentikacije.

Optimize Image

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

Vrne sliko z navedenim CID, pretvorjeno glede na predložene poizvedbene parametre. Če parametri pretvorbe niso podani, se zahteva s 302 preusmeri na izvirno sliko na IPFS prehodu.

Parametri poti

Parameter	Tip	Obvezno	Opis
cid	string	Da	IPFS identifikator vsebine slike.

Poizvedbeni parametri

Parameter	Tip	Privzeto	Opis
w	integer	—	Izhodna širina v slikovnih pikah. Razpon: 1–4096. Vrednosti ≤ 0 ali neštevilske so prezrte.
h	integer	—	Izhodna višina v slikovnih pikah. Razpon: 1–4096. Vrednosti ≤ 0 ali neštevilske so prezrte.
format	string	—	Izhodni format: webp, jpeg, png ali avif. Razlikuje med velikimi in malimi črkami (male črke). Neznane vrednosti so prezrte.
quality	integer	80	Kakovost stiskanja, 1–100. Velja samo za webp, jpeg in avif. png je brez izgub in to prezre.
fit	string	cover	Kako naj se slika prilega dimenzijam: cover, contain, fill, inside ali outside.

Opomba: parameter je quality, ne q. Pogosti skrajšani vzdevki (q, width, height, fmt) niso prepoznani.

Zahteva, ki ne vsebuje nobenega od w, h ali format, se obravnava kot brez operacije in se s 302 preusmeri na izvirno sliko. quality in fit sami ne sprožita pretvorbe.

Načini prilagajanja

Način	Vedenje
cover	Obreže za pokritje obeh dimenzij (privzeto).
contain	Se prilagodi obema dimenzijama in ohrani razmerje stranic. Lahko pusti prazen prostor (prozoren ali črn glede na format).
fill	Razteg za natančno zapolnitev obeh dimenzij. Lahko popači sliko.
inside	Kot contain, vendar samo pomanjšuje, nikoli ne povečuje.
outside	Kot cover, vendar samo pomanjšuje, nikoli ne povečuje.

Povečevanje

Pretvornik nikoli ne poveča slike preko njenih izvornih dimenzij. Če zahtevate w=2000 za vir širine 1200px, bo izhod širok 1200px. To velja za vse načine fit.

Odgovor

Status	Kdaj	Telo
200	Pretvorba je bila izvedena na tej zahtevi.	Binarni bajti slike. Content-Type ustreza zahtevanemu formatu.
302	Parametri pretvorbe niso bili podani ali pa je prej pretvorjen rezultat že predpomnjen.	Glava Location kaže na izvirno sliko ali predpomnjeni rezultat na https://ipfs.ninja/image-cache/....
400	Manjka parameter poti cid.	{ "error": "cid required" }
404	CID na prehodu ni najden.	{ "error": "CID not found" }
500	Nepričakovana napaka (poškodovana slika, neuspela pretvorba itd.).	{ "error": "<message>" }

Vsi odgovori 200 in 302-predpomnilnik so postreženi z glavo Cache-Control: public, max-age=31536000, immutable. Glejte Predpomnjenje spodaj.

Primeri zahtev

Sprememba velikosti na 400px širine, pretvorba v WebP:

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

Sprememba velikosti in obrez na sličico 200×200 kot JPEG s 60% kakovostjo:

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

Kvadratna sličica z letterboxingom namesto obreza:

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

Samo pretvorba formata, brez spremembe velikosti (uporabno za postrežbo različic AVIF/WebP starejših JPEG-ov):

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

Omejitev največje širine brez vsiljevanja višine (ohrani razmerje):

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

Uporaba v HTML

Sklicujte se na optimizirane slike neposredno v oznakah img:

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

Postrezite različne velikosti s 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"
/>

Pogajanje za sodoben format z <picture> (AVIF → WebP → JPEG nadomestek):

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

Uporaba z Next.js

Kot loader po meri za 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}
/>;

Predpomnjenje

Odgovori so postreženi z glavo Cache-Control: public, max-age=31536000, immutable. Ker je vsebina IPFS naslovljena z vsebino, isti CID z istimi parametri vedno proizvede isti izhod, zato lahko brskalniki in CDN-ji predpomnijo odgovore za nedoločen čas.

Predpomnjene pretvorbe so shranjene v S3 s ključem po celotnem naboru parametrov (cid, w, h, format, quality, fit). Naknadne zahteve z istimi parametri vrnejo preusmeritev 302 na predpomnilnik za CloudFrontom (https://ipfs.ninja/image-cache/...) namesto ponovnega izvajanja pretvorbe. Različne kombinacije parametrov proizvajajo različne vnose v predpomnilniku.

Razpoložljivost

Optimizacija slik je na voljo v vseh paketih, vključno z brezplačnim paketom Dharma.