Referencia de API

Sharp proporciona una API rica para procesar imágenes. Esta página proporciona una referencia detallada de todos los métodos disponibles.

Constructor

sharp(input, options?)

Crea una nueva instancia de Sharp.

import sharp from 'sharp';

// Crear desde archivo
const image = sharp('input.jpg');

// Crear desde Buffer
const image = sharp(buffer);

// Crear desde Stream
const image = sharp(stream);

// Crear imagen en blanco
const image = sharp({
  create: {
    width: 300,
    height: 200,
    channels: 4,
    background: { r: 255, g: 0, b: 0, alpha: 1 }
  }
});

Metadatos de Entrada

metadata()

Obtiene información de metadatos de la imagen.

const metadata = await sharp('input.jpg').metadata();
console.log(metadata);
// {
//   format: 'jpeg',
//   width: 1920,
//   height: 1080,
//   space: 'srgb',
//   channels: 3,
//   depth: 'uchar',
//   density: 72,
//   hasProfile: false,
//   hasAlpha: false
// }

stats()

Obtiene información estadística de la imagen.

const stats = await sharp('input.jpg').stats();
console.log(stats);
// {
//   isOpaque: true,
//   dominant: { r: 128, g: 128, b: 128 }
// }

Opciones de Salida

toFile(filename, callback?)

Guarda la imagen procesada en un archivo.

await sharp('input.jpg')
  .resize(300, 200)
  .toFile('output.jpg');

toBuffer(options?, callback?)

Convierte la imagen procesada a Buffer.

const buffer = await sharp('input.jpg')
  .resize(300, 200)
  .jpeg()
  .toBuffer();

toFormat(format, options?)

Establece el formato de salida.

// JPEG
await sharp('input.png')
  .jpeg({ quality: 80, progressive: true })
  .toFile('output.jpg');

// PNG
await sharp('input.jpg')
  .png({ compressionLevel: 9, adaptiveFiltering: true })
  .toFile('output.png');

// WebP
await sharp('input.jpg')
  .webp({ quality: 80, effort: 6 })
  .toFile('output.webp');

// AVIF
await sharp('input.jpg')
  .avif({ quality: 80, effort: 4 })
  .toFile('output.avif');

// TIFF
await sharp('input.jpg')
  .tiff({ quality: 80, compression: 'lzw' })
  .toFile('output.tiff');

Ajuste de Imagen

resize(width?, height?, options?)

Redimensiona la imagen.

// Redimensionamiento básico
await sharp('input.jpg')
  .resize(300, 200)
  .toFile('output.jpg');

// Mantener relación de aspecto
await sharp('input.jpg')
  .resize(300, null)
  .toFile('output.jpg');

// Usar modo de ajuste
await sharp('input.jpg')
  .resize(300, 200, {
    fit: 'cover',        // Recortar para ajustar
    position: 'center',  // Recortar centrado
    background: { r: 255, g: 255, b: 255, alpha: 1 }
  })
  .toFile('output.jpg');

// Usar kernel
await sharp('input.jpg')
  .resize(300, 200, {
    kernel: sharp.kernel.lanczos3
  })
  .toFile('output.jpg');

extract(region)

Recorta una región de la imagen.

await sharp('input.jpg')
  .extract({ left: 100, top: 100, width: 200, height: 200 })
  .toFile('cropped.jpg');

trim(threshold?)

Recorta automáticamente bordes transparentes o blancos.

await sharp('input.png')
  .trim()
  .toFile('trimmed.png');

Operaciones de Imagen

rotate(angle, options?)

Rota la imagen.

// Rotar 90 grados
await sharp('input.jpg')
  .rotate(90)
  .toFile('rotated.jpg');

// Rotar y rellenar fondo
await sharp('input.jpg')
  .rotate(45, { background: { r: 255, g: 255, b: 255, alpha: 1 } })
  .toFile('rotated.jpg');

flip(flip?)

Voltea la imagen verticalmente.

await sharp('input.jpg')
  .flip()
  .toFile('flipped.jpg');

flop(flop?)

Voltea la imagen horizontalmente.

await sharp('input.jpg')
  .flop()
  .toFile('flopped.jpg');

affine(matrix, options?)

Aplica transformación afín.

await sharp('input.jpg')
  .affine([[1, 0.3], [0, 1]], { background: { r: 255, g: 255, b: 255, alpha: 1 } })
  .toFile('transformed.jpg');

Efectos de Filtro

blur(sigma?)

Aplica desenfoque gaussiano.

await sharp('input.jpg')
  .blur(5)
  .toFile('blurred.jpg');

sharpen(sigma?, flat?, jagged?)

Aplica filtro de nitidez.

await sharp('input.jpg')
  .sharpen()
  .toFile('sharpened.jpg');

// Parámetros personalizados de nitidez
await sharp('input.jpg')
  .sharpen(1, 1, 2)
  .toFile('sharpened.jpg');

median(size?)

Aplica filtro mediano.

await sharp('input.jpg')
  .median(3)
  .toFile('median.jpg');

flatten(options?)

Combina canal de transparencia.

await sharp('input.png')
  .flatten({ background: { r: 255, g: 255, b: 255 } })
  .toFile('flattened.jpg');

Operaciones de Color

grayscale(grayscale?)

Convierte a imagen en escala de grises.

await sharp('input.jpg')
  .grayscale()
  .toFile('grayscale.jpg');

negate(negate?)

Efecto negativo.

await sharp('input.jpg')
  .negate()
  .toFile('negated.jpg');

modulate(options?)

Ajusta brillo, saturación y tono.

await sharp('input.jpg')
  .modulate({
    brightness: 1.2,    // Brillo
    saturation: 0.8,    // Saturación
    hue: 90             // Tono
  })
  .toFile('modulated.jpg');

tint(rgb)

Aplica tinte.

await sharp('input.jpg')
  .tint({ r: 255, g: 0, b: 0 })
  .toFile('tinted.jpg');

removeAlpha()

Elimina canal de transparencia.

await sharp('input.png')
  .removeAlpha()
  .toFile('no-alpha.jpg');

ensureAlpha()

Asegura tener canal de transparencia.

await sharp('input.jpg')
  .ensureAlpha()
  .toFile('with-alpha.png');

Operaciones de Canales

bandbool(boolean)

Aplica operación booleana a canales.

await sharp('input.jpg')
  .bandbool('and')
  .toFile('bandbool.jpg');

joinChannel(channels)

Combina canales.

await sharp('input.jpg')
  .joinChannel(['red.jpg', 'green.jpg', 'blue.jpg'])
  .toFile('joined.jpg');

extractChannel(channel)

Extrae un solo canal.

await sharp('input.jpg')
  .extractChannel('red')
  .toFile('red-channel.jpg');

Propiedades Globales

sharp.versions

Obtiene información de versión.

console.log(sharp.versions);
// {
//   sharp: '0.32.0',
//   vips: '8.14.0'
// }

sharp.format

Obtiene formatos soportados.

console.log(sharp.format);
// {
//   jpeg: { id: 'jpeg', ... },
//   png: { id: 'png', ... },
//   webp: { id: 'webp', ... },
//   ...
// }

sharp.kernel

Obtiene kernels disponibles.

console.log(sharp.kernel);
// {
//   nearest: 'nearest',
//   cubic: 'cubic',
//   mitchell: 'mitchell',
//   lanczos2: 'lanczos2',
//   lanczos3: 'lanczos3'
// }

Manejo de Errores

try {
  await sharp('input.jpg')
    .resize(300, 200)
    .toFile('output.jpg');
} catch (error) {
  console.error('Procesamiento de imagen fallido:', error);
}

Optimización de Rendimiento

Procesamiento por Streams

const pipeline = sharp()
  .resize(300, 200)
  .jpeg({ quality: 80 });

fs.createReadStream('large-input.jpg')
  .pipe(pipeline)
  .pipe(fs.createWriteStream('output.jpg'));

Procesamiento Concurrente

const promises = images.map(image => 
  sharp(image)
    .resize(300, 200)
    .jpeg()
    .toBuffer()
);

const results = await Promise.all(promises);

Ejemplo Completo

import sharp from 'sharp';

async function processImage() {
  try {
    // Obtener metadatos
    const metadata = await sharp('input.jpg').metadata();
    console.log('Dimensiones originales:', metadata.width, 'x', metadata.height);

    // Crear múltiples versiones
    const promises = [
      // Miniatura
      sharp('input.jpg')
        .resize(150, 150, { fit: 'cover' })
        .jpeg({ quality: 90 })
        .toFile('thumbnail.jpg'),

      // Tamaño medio
      sharp('input.jpg')
        .resize(800, 600, { fit: 'inside' })
        .webp({ quality: 80 })
        .toFile('medium.webp'),

      // Tamaño grande
      sharp('input.jpg')
        .resize(1920, 1080, { fit: 'inside' })
        .jpeg({ quality: 85, progressive: true })
        .toFile('large.jpg'),

      // Versión en escala de grises
      sharp('input.jpg')
        .grayscale()
        .jpeg({ quality: 80 })
        .toFile('grayscale.jpg')
    ];

    await Promise.all(promises);
    console.log('¡Procesamiento de imágenes completado!');
  } catch (error) {
    console.error('Procesamiento fallido:', error);
  }
}

processImage();

Próximos Pasos

• Ver página de ejemplos para más usos
• Aprender técnicas de optimización de rendimiento
• Ver registro de cambios para conocer las últimas funciones