API de Transformación de Imágenes#

Utiliza la API de Transformación de Imágenes de Snapkit para realizar transformaciones de imágenes en tiempo real mediante parámetros URL. Basada en la biblioteca Sharp↗ para procesamiento de alto rendimiento y CloudFront CDN, proporciona entrega rápida de imágenes en todo el mundo.

Inicio Rápido#

Uso Básico#

Añade parámetros de consulta a las URLs de imágenes subidas para transformación en tiempo real:

GET https://{organization}-cdn.snapkit.studio
  /{project}
  /{path}
  /{filename}
  ?w=800&h=600&fit=cover&flip=true&grayscale=true&dpr=2

Componentes de URL:

{organization}: Nombre de la organización (ej. acme-corp)
{project}: Nombre del proyecto
{path}: Ruta de la carpeta
{filename}: Nombre del archivo de imagen
Parámetros de consulta: Opciones de transformación (w, h, fit, etc.)

Características Principales#

Transformación en tiempo real: Transformación instantánea de imágenes mediante parámetros URL
Caché CDN: Entrega rápida de imágenes desde CloudFront después de la primera transformación
Optimización automática: Selección automática de formato basada en capacidades del navegador
Soporte de alta resolución: Generación de imágenes responsivas basada en DPR (Device Pixel Ratio)

Referencia de Parámetros de Transformación#

Tamaño y Diseño#

Parámetro	Tipo	Descripción	Por Defecto	Límites
`w`	number	Ancho (píxeles)		Máx 4.096px
`h`	number	Alto (píxeles)		Máx 4.096px
`fit`	string	Modo de ajuste: `contain`, `cover`, `fill` , `inside`, `outside`	`cover`
`dpr`	number	Device Pixel Ratio	1.0	1.0-4.0

Transformación y Efectos#

Parámetro	Tipo	Descripción	Límites
`rotation`	number	Ángulo de rotación (0-360 grados, auto-normalizado)
`flip`	boolean	Volteo vertical
`flop`	boolean	Volteo horizontal
`blur`	number	Intensidad de desenfoque	Máx 20
`grayscale`	boolean	Convertir a escala de grises

Región y Formato#

Parámetro	Tipo	Descripción	Límites
`extract`	string	Extraer región: formato `x,y,width,height`	Máx 4.096x4.096
`format`	string	Formato de salida: `jpeg`, `jpg`, `png`, `webp`, `avif`, `auto`

Ejemplos de Uso Práctico#

Optimización de Imágenes Responsivas#

Alta resolución para escritorio

?w=800&h=600&dpr=2.0&format=webp&fit=cover

Optimización móvil

?w=375&dpr=3&format=auto&fit=cover

Generación de miniaturas

?w=200&h=200&fit=cover

Combinaciones Avanzadas de Transformación#

Galería de portafolio

?w=400&h=300&grayscale=true&blur=1&format=webp

Imágenes de productos

?w=600&h=600&fit=contain&format=auto

Vista previa de imagen

?extract=25,25,50,50&w=300&format=jpeg

Opciones Básicas de Transformación#

Redimensionar

?w=800&h=600&fit=cover

Rotar y voltear

?rotation=90&flip=true

Efectos de desenfoque y escala de grises

?blur=2&grayscale=true

Imagen original

Redimensionado aplicado (w=300&h=200&fit=cover)

Visualización de Efectos de Transformación#

Imagen original

Redimensionar + Alta resolución (w=300&h=200&fit=cover&dpr=2.0)

Original

Conversión a escala de grises

Efecto de desenfoque

Original

Desenfoque aplicado (blur=5)

Efecto de rotación (rotation=15)

Uso del Device Pixel Ratio (DPR)#

Ajusta el tamaño real de la imagen para el soporte de pantallas de alta resolución. Calcula el tamaño real de la imagen multiplicando el tamaño especificado por el valor DPR.

Cómo Funciona el DPR#

w=300&dpr=1.0 → Tamaño real de imagen: 300px (300 × 1.0)
w=300&dpr=1.5 → Tamaño real de imagen: 450px (300 × 1.5)
w=300&dpr=2.0 → Tamaño real de imagen: 600px (300 × 2.0)

El navegador sigue mostrando en el tamaño especificado (300px), pero descarga una imagen más grande para renderizado nítido.

DPR 1.0 (real 300px)

DPR 1.5 (real 450px)

DPR 2.0 (real 600px)

Ejemplos de Uso#

Resolución estándar de escritorio

?w=400&h=300&dpr=2

Móvil Retina de alta resolución

?w=400&h=300&dpr=3

Orden de Procesamiento de Transformaciones#

Las transformaciones de imágenes se procesan en el siguiente orden:

Resize (ajuste de tamaño) - DPR aplicado
Rotation (rotación)
Flip/Flop (volteo)
Blur (efecto de desenfoque)
Grayscale (conversión a escala de grises)
Extract (extracción de región)
Format (conversión de formato)

Ejemplos de Transformaciones Complejas#

Puedes combinar múltiples transformaciones:

Ajuste de tamaño + escala de grises + desenfoque

?w=400&h=300&grayscale=true&blur=2

Extracción de región + rotación

?extract=25,25,50,50&rotation=90

Optimización para pantallas de alta resolución

?w=400&h=300&dpr=2.0&format=webp

Imágenes responsivas móviles

?w=375&dpr=1.5&format=auto&fit=cover

Combinación de rotación y volteo

?rotation=45&flip=true&blur=1

Rendimiento y Caché#

CloudFront CDN#

Todas las imágenes transformadas se almacenan en caché en CloudFront CDN para entrega rápida:

Primera solicitud: Transformar imagen original y almacenar en caché
Solicitudes posteriores: Entrega instantánea desde caché
Duración del caché: 1 año

Optimización Basada en Accept Header#

Cuando el parámetro format es auto, el formato óptimo se selecciona automáticamente basado en el Accept header del navegador:

Navegadores compatibles con AVIF: Conversión a formato AVIF
Navegadores compatibles con WebP: Conversión a formato WebP
Navegadores estándar: Conversión a formato JPEG/PNG

Limitaciones del Sistema y Salvaguardas#

Limitaciones de Procesamiento#

Tamaño máximo de imagen: 4.096 x 4.096 píxeles
Límite de píxeles de entrada: 268.402.689 píxeles (aproximadamente 16K x 16K)
Intensidad de desenfoque: Máximo 20 (protección de CPU)
Rango DPR: 1.0-4.0

Sistema de Fallback Automático#

Manejo automático cuando ocurren problemas durante la transformación:

Errores de parámetros: Corrección automática de valores inválidos
Fallos de transformación: Devuelve imagen original
Escasez de memoria: Las limitaciones de procesamiento aseguran la seguridad del sistema
Errores de formato: Conversión a formato JPEG por defecto

Optimización de Memoria#

Caché deshabilitado: Caché de memoria Sharp no utilizado
Limpieza automática: Liberación automática de instancias de biblioteca Sharp después de completar el procesamiento
Procesamiento único: Concurrencia limitada para protección de memoria

Integración y Uso#

Integración Next.js (Próximamente)#

Actualmente en desarrollo. Disponible próximamente.

Mantente actualizado:

Únete a nuestra Comunidad Discord↗
Marca con estrella y sigue nuestro Repositorio GitHub↗
Revisa actualizaciones en nuestro blog

import { Image } from "@snapkit/nextjs";
 
<Image
  src="https://{organization}-<your-org>-cdn.snapkit.studio/{project}/images/hero.jpg"
  alt="Hero"
  width={800}
  height={600}
  transforms={{
    blur: 0,
    format: "auto",
    dpr: 2.0,
  }}
/>;

Implementación de Imágenes Responsivas#

const getResponsiveUrl = (src: string, width: number, mobile = false) => {
  const dpr = mobile ? 1.5 : 3.0;
  return `${src}?w=${width}&dpr=${dpr}&fit=cover&format=auto`;
};
 
// Ejemplo de uso
<picture>
  <source media="(min-width: 768px)" srcSet={getResponsiveUrl(baseUrl, 800)} />
  <img src={getResponsiveUrl(baseUrl, 400, true)} alt="Responsive" />
</picture>;

Próximos Pasos#

Guía de Integración Next.js - Integra con aplicaciones web usando @snapkit/nextjs
Uso del Plugin de Figma - Optimización directa de imágenes desde flujos de trabajo de diseño
Consejos de Optimización de Rendimiento - Estrategias para mejorar la velocidad de carga del sitio web