Back to blog
2026-03-19

Cómo usar la API de Deflato: Tutorial para desarrolladores

¿Por qué usar una API de compresión de imágenes?

La compresión manual no escala. Si tu aplicación maneja subidas de usuarios, genera miniaturas, procesa catálogos de productos o construye sitios estáticos con cientos de páginas, necesitas optimización programática. Una API te permite comprimir, redimensionar y convertir imágenes como parte de tu flujo automatizado.

La API de Deflato ofrece una interfaz REST simple para compresión y conversión de imágenes. Soporta JPEG, PNG, WebP, AVIF, HEIC, TIFF y PDF como entrada, con JPEG, WebP y AVIF como salida.

Obtener tu clave API

  1. Crea una cuenta en deflato.com.
  2. Navega a Settings → API en tu panel.
  3. Haz clic en Generate API Key. Copia la clave — solo se mostrará una vez.
  4. Almacena la clave de forma segura. Usa variables de entorno (DEFLATO_API_KEY) en lugar de incluirla en el código fuente.

El plan gratuito incluye 100 compresiones API al mes. Los planes Pro y Team ofrecen límites superiores.

Fundamentos de la API: Ejemplos con cURL

La API expone un único endpoint:

POST https://deflato.com/api/v1/compress

Acepta multipart/form-data con el archivo de imagen y parámetros opcionales.

Compresión básica

# Comprimir un JPEG con configuración predeterminada
curl -X POST https://deflato.com/api/v1/compress   -H "Authorization: Bearer $DEFLATO_API_KEY"   -F "file=@photo.jpg"   --output compressed.jpg

Sin parámetros adicionales, la API aplica valores predeterminados: mismo formato de salida, calidad 80, sin redimensionado, EXIF eliminado.

Conversión de formato

# Convertir JPEG a WebP
curl -X POST https://deflato.com/api/v1/compress   -H "Authorization: Bearer $DEFLATO_API_KEY"   -F "file=@photo.jpg"   -F "output_format=WEBP"   -F "quality=80"   --output photo.webp

Redimensionar y comprimir

# Redimensionar a máx 1920px, convertir a AVIF a calidad 70
curl -X POST https://deflato.com/api/v1/compress   -H "Authorization: Bearer $DEFLATO_API_KEY"   -F "file=@photo.jpg"   -F "output_format=AVIF"   -F "quality=70"   -F "max_dimension=1920"   --output photo.avif

Conversión HEIC a JPEG

# Convertir foto HEIC de iPhone a JPEG
curl -X POST https://deflato.com/api/v1/compress   -H "Authorization: Bearer $DEFLATO_API_KEY"   -F "file=@IMG_1234.heic"   -F "output_format=JPEG"   -F "quality=85"   --output photo.jpg

Referencia de parámetros de la API

Parámetro Tipo Predeterminado Descripción
file File requerido Archivo de imagen (JPEG, PNG, WebP, AVIF, HEIC, TIFF o PDF)
output_format String Igual que entrada Formato de salida: JPEG, WEBP o AVIF
quality Integer 80 Calidad de compresión (1–100). Menor = archivo más pequeño, más artefactos
max_dimension Integer 0 (sin redimensionar) Ancho o alto máximo en píxeles. La imagen se escala proporcionalmente
strip_exif Boolean true Eliminar EXIF/metadatos de la salida

SDK de Python

Instala el SDK vía pip:

pip install deflato

Uso básico

import deflato

client = deflato.Client(api_key="YOUR_API_KEY")

# Comprimir una imagen
result = client.compress(
    "photo.jpg",
    output_format="WEBP",
    quality=80,
    max_dimension=1920
)
result.save("photo.webp")

print(f"Original: {result.original_size / 1024:.0f} KB")
print(f"Comprimido: {result.compressed_size / 1024:.0f} KB")
print(f"Ahorro: {result.savings_percent:.1f}%")

Procesamiento por lotes

import deflato
from pathlib import Path

client = deflato.Client(api_key="YOUR_API_KEY")

input_dir = Path("./images")
output_dir = Path("./optimized")
output_dir.mkdir(exist_ok=True)

for image_path in input_dir.glob("*.jpg"):
    result = client.compress(
        str(image_path),
        output_format="WEBP",
        quality=80
    )
    result.save(output_dir / f"{image_path.stem}.webp")
    print(f"{image_path.name}: {result.savings_percent:.1f}% ahorrado")

Uso con Django

# En tu vista o signal handler de Django
import deflato
from django.core.files.base import ContentFile

client = deflato.Client(api_key=settings.DEFLATO_API_KEY)

def optimize_upload(instance, **kwargs):
    if instance.image:
        result = client.compress(
            instance.image.path,
            output_format="WEBP",
            quality=80,
            max_dimension=1600
        )
        # Guardar versión optimizada
        instance.image.save(
            f"{instance.image.name.rsplit('.', 1)[0]}.webp",
            ContentFile(result.content),
            save=False
        )

SDK de Node.js

Instala vía npm:

npm install deflato

Uso básico

const Deflato = require('deflato');
const fs = require('fs');

const client = new Deflato({ apiKey: process.env.DEFLATO_API_KEY });

async function compressImage() {
  const result = await client.compress('./photo.jpg', {
    outputFormat: 'WEBP',
    quality: 80,
    maxDimension: 1920
  });

  fs.writeFileSync('./photo.webp', result.buffer);

  console.log(`Original: ${(result.originalSize / 1024).toFixed(0)} KB`);
  console.log(`Comprimido: ${(result.compressedSize / 1024).toFixed(0)} KB`);
  console.log(`Ahorro: ${result.savingsPercent.toFixed(1)}%`);
}

compressImage();

Procesamiento por lotes con control de concurrencia

const Deflato = require('deflato');
const fs = require('fs');
const path = require('path');
const { promisify } = require('util');
const glob = promisify(require('glob'));

const client = new Deflato({ apiKey: process.env.DEFLATO_API_KEY });

async function batchCompress(inputDir, outputDir, concurrency = 5) {
  const files = await glob(`${inputDir}/*.{jpg,png,jpeg}`);
  fs.mkdirSync(outputDir, { recursive: true });

  // Procesar en lotes para respetar límites de tasa
  for (let i = 0; i < files.length; i += concurrency) {
    const batch = files.slice(i, i + concurrency);
    const results = await Promise.all(
      batch.map(async (file) => {
        const result = await client.compress(file, {
          outputFormat: 'WEBP',
          quality: 80
        });
        const outPath = path.join(
          outputDir,
          path.basename(file, path.extname(file)) + '.webp'
        );
        fs.writeFileSync(outPath, result.buffer);
        return { file: path.basename(file), savings: result.savingsPercent };
      })
    );
    results.forEach(r =>
      console.log(`${r.file}: ${r.savings.toFixed(1)}% ahorrado`)
    );
  }
}

batchCompress('./images', './optimized');

Integración con servidor MCP

Deflato proporciona un servidor MCP (Model Context Protocol) que permite a asistentes de IA comprimir imágenes directamente. Útil para flujos de trabajo impulsados por IA.

Configuración

Añade el servidor MCP de Deflato a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "deflato": {
      "command": "npx",
      "args": ["-y", "deflato-mcp-server"],
      "env": {
        "DEFLATO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Una vez configurado, tu asistente de IA puede llamar a las herramientas de Deflato para comprimir, convertir y redimensionar imágenes como parte de su flujo de trabajo.

Manejo de errores

La API devuelve códigos de estado HTTP estándar:

  • 200 — Éxito. El cuerpo de respuesta es la imagen comprimida.
  • 400 — Solicitud incorrecta. Verifica los parámetros.
  • 401 — No autorizado. La clave API es inválida o falta.
  • 413 — Archivo demasiado grande. Excede el límite de subida (50 MB para planes Pro).
  • 429 — Límite de tasa excedido. Espera y reintenta con backoff exponencial.
  • 500 — Error del servidor. Reintenta la solicitud.

En Python:

import deflato

client = deflato.Client(api_key="YOUR_API_KEY")

try:
    result = client.compress("photo.jpg", output_format="WEBP", quality=80)
    result.save("photo.webp")
except deflato.AuthenticationError:
    print("Clave API inválida")
except deflato.RateLimitError as e:
    print(f"Límite de tasa excedido. Reintentar después de {e.retry_after} segundos")
except deflato.FileTooLargeError:
    print("El archivo excede el tamaño máximo de subida")
except deflato.APIError as e:
    print(f"Error de API: {e.message}")

Límites de tasa y precios

Plan Compresiones API / Mes Tamaño máx. archivo Límite de tasa
Free 100 10 MB 10 req/min
Pro 10,000 50 MB 60 req/min
Team 100,000 100 MB 300 req/min
Enterprise Personalizado Personalizado Personalizado

Consulta tu uso actual vía API:

curl https://deflato.com/api/v1/usage   -H "Authorization: Bearer $DEFLATO_API_KEY"
{
  "plan": "pro",
  "compressions_used": 1847,
  "compressions_limit": 10000,
  "period_ends": "2026-04-01T00:00:00Z"
}

Mejores prácticas

  • Cachea resultados — No recomprimas la misma imagen dos veces. Almacena versiones comprimidas y omite archivos sin cambios.
  • Usa variables de entorno para tu clave API. Nunca la incluyas en el control de versiones.
  • Implementa lógica de reintento con backoff exponencial para respuestas 429 y 500.
  • Establece un timeout — Imágenes grandes pueden tardar algunos segundos. Configura un timeout razonable (30s).
  • Comprime al subir, no al solicitar — Optimiza imágenes cuando se suben, no cuando un usuario las solicita.
  • Monitorea el uso — Usa el endpoint /usage para rastrear el consumo y alertar antes de alcanzar el límite.

Conclusión

La API de Deflato convierte la optimización de imágenes de una tarea manual en un paso automatizado del pipeline. Ya sea que proceses subidas de usuarios, construyas un sitio estático con miles de imágenes o integres compresión en un flujo de IA vía MCP, la API ofrece una interfaz consistente: sube una imagen, especifica parámetros y obtén un resultado optimizado. Comienza con los ejemplos de cURL para validar tu flujo, luego integra el SDK de Python o Node.js para producción.

Try Deflato — compress your images for free

Reduce file sizes by up to 90% with no visible quality loss. Supports JPEG, PNG, WebP, AVIF, PDF, and Office documents.

Compress Images Now