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 indicado, transformada según los parámetros de consulta proporcionados. Si no se proporcionan parámetros de transformación, la solicitud devuelve una redirección 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	—	Anchura de salida en píxeles. Rango: 1–4096. Los valores ≤ 0 o no numéricos se ignoran.
h	integer	—	Altura 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 se aplica a webp, jpeg y avif. png es sin pérdidas y lo ignora.
fit	string	cover	Cómo debe ajustarse la imagen a las dimensiones: cover, contain, fill, inside o outside.

Nota: el parámetro es quality, no q. Los alias abreviados habituales (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 una redirección 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 rellenar ambas dimensiones exactamente. Puede distorsionar la imagen.
inside	Como contain, pero solo reduce, nunca aumenta.
outside	Como cover, pero solo reduce, nunca aumenta.

Escalado al alza

El transformador nunca amplía una imagen más allá de las dimensiones de su origen. Si solicitas w=2000 para un origen de 1200px de anchura, la salida tendrá 1200px de anchura. Esto se 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 ya hay un resultado previamente transformado en cache.	La cabecera Location apunta a la imagen original o al resultado en cache 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 de cache 302 se sirven con Cache-Control: public, max-age=31536000, immutable. Consulta Cache más abajo.

Ejemplos de solicitudes

Redimensionar a 400px de anchura, 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 recortar:

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 la anchura máxima 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, por lo que los navegadores y CDNs pueden almacenar las respuestas en cache indefinidamente.

Las transformaciones cacheadas 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 una redirección 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.