Ottimizzazione delle Immagini

Trasforma e ottimizza le immagini servite da IPFS al volo utilizzando parametri di query. Questo è un endpoint pubblico che non richiede autenticazione.

Ottimizza Immagine

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

Restituisce l'immagine al CID specificato, trasformata in base ai parametri di query forniti. Se non vengono forniti parametri di trasformazione, la richiesta restituisce un reindirizzamento 302 all'immagine originale sul gateway IPFS.

Parametri di percorso

Parametro	Tipo	Richiesto	Descrizione
cid	string	Si	L'identificatore di contenuto IPFS dell'immagine.

Parametri di query

Parametro	Tipo	Predefinito	Descrizione
w	integer	—	Larghezza di output in pixel. Intervallo: 1–4096. I valori ≤ 0 o non numerici vengono ignorati.
h	integer	—	Altezza di output in pixel. Intervallo: 1–4096. I valori ≤ 0 o non numerici vengono ignorati.
format	string	—	Formato di output: webp, jpeg, png o avif. Distingue maiuscole e minuscole (in minuscolo). I valori sconosciuti vengono ignorati.
quality	integer	80	Qualità di compressione, 1–100. Si applica solo a webp, jpeg e avif. png è senza perdita e lo ignora.
fit	string	cover	Come l'immagine deve adattarsi alle dimensioni: cover, contain, fill, inside o outside.

Nota: il parametro è quality, non q. Gli alias abbreviati comuni (q, width, height, fmt) non sono riconosciuti.

Una richiesta che non fornisce nessuno di w, h o format viene trattata come un'operazione neutra e restituisce un reindirizzamento 302 all'immagine originale. quality e fit da soli non attivano una trasformazione.

Modalità di adattamento

Modalità	Comportamento
cover	Ritaglia per coprire entrambe le dimensioni (predefinito).
contain	Adatta entro entrambe le dimensioni, preservando il rapporto d'aspetto. Può lasciare spazio vuoto (trasparente o nero a seconda del formato).
fill	Allunga per riempire esattamente entrambe le dimensioni. Può distorcere l'immagine.
inside	Come contain, ma riduce soltanto, non ingrandisce mai.
outside	Come cover, ma riduce soltanto, non ingrandisce mai.

Ingrandimento

Il trasformatore non ingrandisce mai un'immagine oltre le dimensioni della sorgente. Se richiedi w=2000 per una sorgente larga 1200px, l'output sarà largo 1200px. Questo si applica a tutte le modalità fit.

Risposta

Stato	Quando	Corpo
200	È stata prodotta una trasformazione su questa richiesta.	Byte binari dell'immagine. Content-Type corrisponde al formato richiesto.
302	Nessun parametro di trasformazione fornito, o un risultato già trasformato è già in cache.	L'intestazione Location punta all'immagine originale o al risultato in cache su https://ipfs.ninja/image-cache/....
400	Parametro di percorso cid mancante.	{ "error": "cid required" }
404	CID non trovato sul gateway.	{ "error": "CID not found" }
500	Errore inatteso (immagine corrotta, fallimento della trasformazione, ecc.).	{ "error": "<message>" }

Tutte le risposte 200 e quelle 302 dalla cache vengono servite con Cache-Control: public, max-age=31536000, immutable. Vedi Cache qui sotto.

Esempi di richieste

Ridimensionare a 400px di larghezza, convertire in WebP:

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

Ridimensionare e ritagliare a miniatura 200×200 come JPEG al 60% di qualità:

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

Miniatura quadrata con bande anziché ritaglio:

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

Solo conversione di formato, senza ridimensionamento (utile per servire versioni AVIF/WebP di JPEG legacy):

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

Limitare la larghezza massima senza forzare l'altezza (preserva il rapporto d'aspetto):

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

Utilizzo in HTML

Referenzia le immagini ottimizzate direttamente nei tag img:

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

Servi diverse dimensioni con 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"
/>

Negoziazione di formati moderni con <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>

Immagine di sfondo CSS:

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

Utilizzo con Next.js

Come loader personalizzato per 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

Le risposte vengono servite con Cache-Control: public, max-age=31536000, immutable. Poiché il contenuto IPFS è indirizzato per contenuto, lo stesso CID con gli stessi parametri produce sempre lo stesso output, quindi browser e CDN possono mantenere le risposte in cache indefinitamente.

Le trasformazioni in cache sono memorizzate in S3 indicizzate dall'insieme completo di parametri (cid, w, h, format, quality, fit). Le richieste successive con gli stessi parametri restituiscono un reindirizzamento 302 alla cache servita da CloudFront (https://ipfs.ninja/image-cache/...) anziché rieseguire la trasformazione. Combinazioni di parametri diverse producono voci di cache diverse.

Disponibilità

L'ottimizzazione delle immagini è disponibile su tutti i piani, incluso il piano gratuito Dharma.