Optimización de Imágenes

Transforma y optimiza imágenes servidas desde IPFS al vuelo usando parámetros de consulta. Este es un endpoint público que no requiere autenticación.

Optimizar Imagen

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

Devuelve la imagen en el CID dado, transformada según los parámetros de consulta proporcionados. Si no se proporcionan parámetros de transformación, la solicitud devuelve un redireccionamiento 302 a la imagen original en la pasarela IPFS.

Parámetros de ruta

Parámetro	Tipo	Requerido	Descripción
cid	string	Sí	El identificador de contenido IPFS de la imagen.

Parámetros de consulta

Parámetro	Tipo	Por defecto	Descripción
w	integer	—	Ancho de salida en píxeles. Rango: 1–4096. Los valores ≤ 0 o no numéricos se ignoran.
h	integer	—	Alto de salida en píxeles. Rango: 1–4096. Los valores ≤ 0 o no numéricos se ignoran.
format	string	—	Formato de salida: webp, jpeg, png o avif. Distingue mayúsculas y minúsculas (en minúsculas). Los valores desconocidos se ignoran.
quality	integer	80	Calidad de compresión, 1–100. Solo aplica a webp, jpeg y avif. png es sin pérdida y lo ignora.
fit	string	cover	Cómo la imagen debe ajustarse a las dimensiones: cover, contain, fill, inside o outside.

Nota: el parámetro es quality, no q. Los alias abreviados comunes (q, width, height, fmt) no se reconocen.

Una solicitud que no proporcione ninguno de w, h o format se trata como una operación nula y devuelve un redireccionamiento 302 a la imagen original. quality y fit por sí solos no activan una transformación.

Modos de ajuste

Modo	Comportamiento
cover	Recortar para cubrir ambas dimensiones (por defecto).
contain	Ajustar dentro de ambas dimensiones, preservando la relación de aspecto. Puede dejar espacio vacío (transparente o negro según el formato).
fill	Estirar para llenar ambas dimensiones exactamente. Puede distorsionar la imagen.
inside	Como contain, pero solo reduce, nunca aumenta.
outside	Como cover, pero solo reduce, nunca aumenta.

Escalado hacia arriba

El transformador nunca agranda una imagen más allá de las dimensiones de su origen. Si solicitas w=2000 para un origen de 1200px de ancho, la salida será de 1200px de ancho. Esto aplica a todos los modos fit.

Respuesta

Estado	Cuándo	Cuerpo
200	Se produjo una transformación en esta solicitud.	Bytes binarios de la imagen. Content-Type coincide con el formato solicitado.
302	No se proporcionaron parámetros de transformación, o un resultado previamente transformado ya está en caché.	El encabezado Location apunta a la imagen original o al resultado en caché en https://ipfs.ninja/image-cache/....
400	Falta el parámetro de ruta cid.	{ "error": "cid required" }
404	CID no encontrado en la pasarela.	{ "error": "CID not found" }
500	Error inesperado (imagen corrupta, fallo de transformación, etc.).	{ "error": "<message>" }

Todas las respuestas 200 y 302 desde caché se sirven con Cache-Control: public, max-age=31536000, immutable. Consulta Cache más abajo.

Ejemplos de solicitudes

Redimensionar a 400px de ancho, convertir a WebP:

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

Redimensionar y recortar a miniatura de 200×200 como JPEG al 60% de calidad:

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

Miniatura cuadrada con bandas en lugar de recorte:

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

Solo conversión de formato, sin redimensionar (útil para servir versiones AVIF/WebP de JPEGs heredados):

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

Limitar el ancho máximo sin forzar la altura (preserva la relación de aspecto):

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

Uso en HTML

Referencia imágenes optimizadas directamente en etiquetas img:

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

Sirve diferentes tamaños 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"
/>

Negociación de formatos modernos con <picture> (AVIF → WebP → respaldo 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>

Imagen de fondo en CSS:

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

Uso con Next.js

Como cargador personalizado para 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

Las respuestas se sirven con Cache-Control: public, max-age=31536000, immutable. Dado que el contenido IPFS es direccionado por contenido, el mismo CID con los mismos parámetros siempre produce la misma salida, así que los navegadores y CDNs pueden almacenar las respuestas en cache indefinidamente.

Las transformaciones en cache se almacenan en S3 indexadas por el conjunto completo de parámetros (cid, w, h, format, quality, fit). Las solicitudes posteriores con los mismos parámetros devuelven un redireccionamiento 302 al cache servido por CloudFront (https://ipfs.ninja/image-cache/...) en lugar de volver a ejecutar la transformación. Combinaciones distintas de parámetros producen entradas de cache distintas.

Disponibilidad

La optimización de imágenes está disponible en todos los planes, incluido el plan gratuito Dharma.