Optimitzacio d'Imatge

Transformeu i optimitzeu imatges servides des d'IPFS sobre la marxa utilitzant parametres de consulta. Aquest es un endpoint public que no requereix autenticacio.

Optimitzar Imatge

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

Retorna la imatge al CID indicat, transformada segons els parametres de consulta proporcionats. Si no es proporcionen parametres de transformacio, la sol·licitud retorna una redireccio 302 a la imatge original a la passarel·la IPFS.

Parametres de ruta

Parametre	Tipus	Requerit	Descripcio
cid	string	Si	L'identificador de contingut IPFS de la imatge.

Parametres de consulta

Parametre	Tipus	Per defecte	Descripcio
w	integer	—	Amplada de sortida en pixels. Rang: 1–4096. Els valors ≤ 0 o no numerics s'ignoren.
h	integer	—	Alcada de sortida en pixels. Rang: 1–4096. Els valors ≤ 0 o no numerics s'ignoren.
format	string	—	Format de sortida: webp, jpeg, png o avif. Distingeix majuscules i minuscules (en minuscules). Els valors desconeguts s'ignoren.
quality	integer	80	Qualitat de compressio, 1–100. Nomes s'aplica a webp, jpeg i avif. png es sense perdua i l'ignora.
fit	string	cover	Com ha d'encaixar la imatge a les dimensions: cover, contain, fill, inside o outside.

Nota: el parametre es quality, no q. Els alies abreujats habituals (q, width, height, fmt) no es reconeixen.

Una sol·licitud que no proporcioni cap de w, h o format es tracta com una operacio nul·la i retorna una redireccio 302 a la imatge original. quality i fit per si sols no activen una transformacio.

Modes d'encaix

Mode	Comportament
cover	Retallar per cobrir ambdues dimensions (per defecte).
contain	Encaixar dins d'ambdues dimensions, preservant la relacio d'aspecte. Pot deixar espai buit (transparent o negre segons el format).
fill	Estirar per omplir ambdues dimensions exactament. Pot distorsionar la imatge.
inside	Com contain, pero nomes redueix, mai augmenta.
outside	Com cover, pero nomes redueix, mai augmenta.

Escalat a l'alca

El transformador mai engrandeix una imatge mes enlla de les dimensions del seu origen. Si demaneu w=2000 per a un origen de 1200px d'amplada, la sortida sera de 1200px d'amplada. Aixo s'aplica a tots els modes fit.

Resposta

Estat	Quan	Cos
200	S'ha produit una transformacio en aquesta sol·licitud.	Bytes binaris de la imatge. Content-Type coincideix amb el format sol·licitat.
302	No s'han proporcionat parametres de transformacio, o un resultat transformat previament ja esta en cache.	La capcalera Location apunta a la imatge original o al resultat en cache a https://ipfs.ninja/image-cache/....
400	Falta el parametre de ruta cid.	{ "error": "cid required" }
404	CID no trobat a la passarel·la.	{ "error": "CID not found" }
500	Error inesperat (imatge corrupta, fallada de transformacio, etc.).	{ "error": "<message>" }

Totes les respostes 200 i les de cache 302 se serveixen amb Cache-Control: public, max-age=31536000, immutable. Vegeu Caching mes avall.

Exemples de sol·licituds

Redimensionar a 400px d'amplada, convertir a WebP:

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

Redimensionar i retallar a miniatura de 200×200 com a JPEG al 60% de qualitat:

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

Miniatura quadrada amb bandes en lloc de retallar:

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

Nomes conversio de format, sense redimensionar (util per servir versions AVIF/WebP de JPEGs antics):

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

Limitar l'amplada maxima sense forcar l'alcada (preserva la relacio d'aspecte):

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

Us en HTML

Referencieu imatges optimitzades directament en etiquetes img:

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

Serviu diferents mides amb 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"
/>

Negociacio de formats moderns amb <picture> (AVIF → WebP → alternativa 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>

Imatge de fons CSS:

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

Us amb Next.js

Com a carregador personalitzat per a 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

Les respostes se serveixen amb Cache-Control: public, max-age=31536000, immutable. Com que el contingut IPFS es adrecat per contingut, el mateix CID amb els mateixos parametres sempre produeix la mateixa sortida, aixi que els navegadors i CDNs poden emmagatzemar les respostes en cache indefinidament.

Les transformacions en cache s'emmagatzemen a S3 indexades pel conjunt complet de parametres (cid, w, h, format, quality, fit). Les sol·licituds posteriors amb els mateixos parametres retornen una redireccio 302 al cache servit per CloudFront (https://ipfs.ninja/image-cache/...) en lloc de tornar a executar la transformacio. Combinacions diferents de parametres produeixen entrades de cache diferents.

Disponibilitat

L'optimitzacio d'imatges esta disponible en tots els plans, incloent-hi el pla gratuit Dharma.