Optimizarea imaginilor

Transformati si optimizati imaginile servite de la IPFS din mers folosind parametri de interogare. Acesta este un endpoint public care nu necesita autentificare.

Optimizare imagine

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

Returneaza imaginea de la CID-ul indicat, transformata in functie de parametrii de interogare furnizati. Daca nu se furnizeaza parametri de transformare, cererea returneaza o redirectionare 302 catre imaginea originala de pe gateway-ul IPFS.

Parametri de cale

Parametru	Tip	Obligatoriu	Descriere
cid	string	Da	Identificatorul de continut IPFS al imaginii.

Parametri de interogare

Parametru	Tip	Implicit	Descriere
w	integer	—	Latimea de iesire in pixeli. Interval: 1–4096. Valorile ≤ 0 sau nenumerice sunt ignorate.
h	integer	—	Inaltimea de iesire in pixeli. Interval: 1–4096. Valorile ≤ 0 sau nenumerice sunt ignorate.
format	string	—	Format de iesire: webp, jpeg, png sau avif. Sensibil la majuscule (cu litere mici). Valorile necunoscute sunt ignorate.
quality	integer	80	Calitatea compresiei, 1–100. Se aplica doar la webp, jpeg si avif. png este fara pierderi si o ignora.
fit	string	cover	Cum trebuie sa se incadreze imaginea in dimensiuni: cover, contain, fill, inside sau outside.

Nota: parametrul este quality, nu q. Aliasurile prescurtate uzuale (q, width, height, fmt) nu sunt recunoscute.

O cerere care nu furnizeaza niciunul dintre w, h sau format este tratata ca o operatie nula si returneaza o redirectionare 302 catre imaginea originala. quality si fit singure nu declanseaza o transformare.

Moduri de incadrare

Mod	Comportament
cover	Decupeaza pentru a acoperi ambele dimensiuni (implicit).
contain	Incadreaza in ambele dimensiuni, pastrand raportul de aspect. Poate lasa spatiu gol (transparent sau negru in functie de format).
fill	Intinde pentru a umple exact ambele dimensiuni. Poate distorsiona imaginea.
inside	Ca contain, dar doar reduce, nu mareste niciodata.
outside	Ca cover, dar doar reduce, nu mareste niciodata.

Marire

Transformatorul nu mareste niciodata o imagine peste dimensiunile sursei. Daca solicitati w=2000 pentru o sursa de 1200px latime, iesirea va avea 1200px latime. Acest lucru se aplica tuturor modurilor fit.

Raspuns

Stare	Cand	Corp
200	S-a produs o transformare la aceasta cerere.	Bytes binari ai imaginii. Content-Type corespunde formatului solicitat.
302	Nu s-au furnizat parametri de transformare, sau un rezultat transformat anterior este deja in cache.	Antetul Location indica imaginea originala sau rezultatul din cache la https://ipfs.ninja/image-cache/....
400	Parametrul de cale cid lipseste.	{ "error": "cid required" }
404	CID negasit pe gateway.	{ "error": "CID not found" }
500	Eroare neasteptata (imagine corupta, esec de transformare, etc.).	{ "error": "<message>" }

Toate raspunsurile 200 si raspunsurile 302 din cache sunt servite cu Cache-Control: public, max-age=31536000, immutable. Vezi Caching mai jos.

Exemple de cereri

Redimensioneaza la 400px latime, converteste la WebP:

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

Redimensioneaza si decupeaza la miniatura 200×200 ca JPEG la 60% calitate:

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

Miniatura patrata cu benzi in loc de decupare:

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

Doar conversie de format, fara redimensionare (util pentru a servi versiuni AVIF/WebP ale JPEG-urilor mai vechi):

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

Limiteaza latimea maxima fara a forta inaltimea (pastreaza raportul de aspect):

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

Utilizare in HTML

Faceti referinta la imaginile optimizate direct in etichetele img:

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

Serviti dimensiuni diferite cu 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"
/>

Negociere moderna a formatelor cu <picture> (AVIF → WebP → fallback 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>

Imagine de fundal CSS:

.hero {
  background-image: url("https://api.ipfs.ninja/image/QmXmCX9S6ANV...?w=1600&format=webp&quality=70");
}

Utilizare cu Next.js

Ca loader personalizat pentru 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}
/>;

Caching

Raspunsurile sunt servite cu Cache-Control: public, max-age=31536000, immutable. Deoarece continutul IPFS este adresat prin continut, acelasi CID cu aceiasi parametri produce intotdeauna aceeasi iesire, asa ca browserele si CDN-urile pot pastra raspunsurile in cache pe termen nelimitat.

Transformarile din cache sunt stocate in S3 indexate dupa setul complet de parametri (cid, w, h, format, quality, fit). Cererile ulterioare cu aceiasi parametri returneaza o redirectionare 302 catre cache-ul servit de CloudFront (https://ipfs.ninja/image-cache/...) in loc sa execute din nou transformarea. Combinatii diferite de parametri produc intrari de cache diferite.

Disponibilitate

Optimizarea imaginilor este disponibila pe toate planurile, inclusiv pe planul gratuit Dharma.