API de escalado de imágenes: Guía de integración para desarrolladores

Integrar escalado de imágenes en tu app solía significar entrenar modelos de IA propios. Eso llevaba meses y un presupuesto grande en GPUs. Con la API de UpscaleIMG, envías una imagen y recibes una versión nítida y ampliada en segundos.

Esta guía te muestra cómo integrar UpscaleIMG en tu proyecto. Con ejemplos de código reales y todas las opciones disponibles.

¿Qué puede hacer la API de UpscaleIMG?

La API de UpscaleIMG usa Real-ESRGAN. Es un modelo de IA potente diseñado para super-resolución de imágenes. Envías una foto y la IA añade detalles realistas al ampliarla. Los bordes se mantienen nítidos. Las texturas lucen naturales. Los rostros conservan sus rasgos.

Esto es lo que obtienes:

• Escalado 2x y 4x con mejora de detalles por IA
• Dimensiones personalizadas para un tamaño de salida específico
• Conversión de formato entre PNG, JPG y WebP
• Control de metadatos para eliminar o conservar datos EXIF
• Hasta 64 megapíxeles de resolución de salida

Todo el procesamiento de IA se ejecuta en nuestros servidores. No necesitas GPU. Sin configurar modelos. Solo envía una petición HTTP y recibe tu resultado.

¿Cómo empiezas con la API?

Necesitas una clave API para hacer peticiones. Así la consigues:

1. Crea una cuenta en upscaleimg.app
2. Ve a tu panel y genera una clave API
3. Guárdala de forma segura en tu servidor

El endpoint de la API es:

POST https://upscaleimg.app/api/v1/upscale

La autenticación usa un token Bearer en el header Authorization. Mantén tu clave API en el servidor. Nunca la expongas en código del cliente ni la subas al repositorio.

Las cuentas gratuitas tienen escalado 2x. Los suscriptores desbloquean 4x y dimensiones personalizadas hasta 4x el tamaño original.

¿Cómo escalas tu primera imagen?

La llamada más simple solo necesita una imagen y un factor de escala. Aquí un ejemplo con curl para 2x:

curl -X POST https://upscaleimg.app/api/v1/upscale \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@photo.jpg" \
  -F "scale=2"

La API devuelve JSON con detalles de la imagen original y la escalada:

{
  "original": {
    "size": 384000,
    "width": 1920,
    "height": 1080,
    "mimeType": "image/jpeg",
    "fileExt": "jpg"
  },
  "result": {
    "size": 1280000,
    "width": 3840,
    "height": 2160,
    "mimeType": "image/png",
    "fileExt": "png",
    "url": "https://..."
  }
}

El campo url te da un enlace de descarga firmado. Descárgalo enseguida porque las URLs firmadas expiran rápido.

Lo mismo en JavaScript:

const form = new FormData();
form.append('image', fileInput.files[0]);
form.append('scale', '2');

const response = await fetch('https://upscaleimg.app/api/v1/upscale', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: form
});

const data = await response.json();
console.log(`Escalado a ${data.result.width}x${data.result.height}`);

Y en Python:

import requests

with open('photo.jpg', 'rb') as f:
    response = requests.post(
        'https://upscaleimg.app/api/v1/upscale',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        files={'image': f},
        data={'scale': '2'}
    )

data = response.json()
print(f"Escalado a {data['result']['width']}x{data['result']['height']}")

¿Qué opciones soporta la API?

La API acepta varios parámetros mediante datos multipart. Aquí la lista completa:

Parámetro	Obligatorio	Valores	Descripción
image	Sí	Archivo	Imagen PNG, JPG, JPEG o WebP
scale	Sí*	2 o 4	Factor de escala. *No necesario con dimensiones personalizadas.
customWidth	No	Entero	Ancho objetivo en píxeles (máx. 4x original)
customHeight	No	Entero	Alto objetivo en píxeles (máx. 4x original)
objectFit	No	cover, contain, fill	Modo de ajuste con dimensiones personalizadas. Por defecto: cover.
outputFormat	No	jpg, jpeg, png, webp	Formato de salida. Por defecto: png.
removeMetadata	No	1 o 0	Eliminar datos EXIF. Por defecto: 0 (conservar).

Dimensiones personalizadas te dan control preciso. customWidth y customHeight deben indicarse juntos. La salida no puede ser menor que el original ni mayor que 4x (2x en cuentas gratuitas).

Por ejemplo, para escalar a exactamente 3000x2000 en WebP:

curl -X POST https://upscaleimg.app/api/v1/upscale \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@photo.jpg" \
  -F "customWidth=3000" \
  -F "customHeight=2000" \
  -F "objectFit=cover" \
  -F "outputFormat=webp" \
  -F "removeMetadata=1"

El parámetro objectFit funciona como CSS object-fit. cover llena las dimensiones exactas (puede recortar). contain ajusta dentro (puede añadir márgenes). fill estira al tamaño exacto.

¿Cómo manejas errores y límites de peticiones?

La API devuelve códigos HTTP estándar:

Código	Significado
200	Éxito. Imagen escalada devuelta.
400	Petición inválida. Imagen faltante, factor inválido o dimensiones fuera de rango.
401	Clave API inválida o faltante.
403	Prohibido. Intento de 4x sin suscripción o error CORS.
429	Límite alcanzado. Demasiadas peticiones.
500	Error del servidor. Inténtalo de nuevo.

Todas las respuestas de error incluyen un mensaje:

{"error": "4x upscaling is only available with an active subscription."}

Para límites de peticiones, añade lógica de reintento con backoff:

async function upscaleWithRetry(form, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch('https://upscaleimg.app/api/v1/upscale', {
      method: 'POST',
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
      body: form
    });

    if (res.status === 429) {
      await new Promise(r => setTimeout(r, 2000 * (i + 1)));
      continue;
    }

    return await res.json();
  }
  throw new Error('Max retries reached');
}

¿Cuáles son los mejores casos de uso?

La API de UpscaleIMG encaja perfectamente en varios flujos de trabajo.

Plataformas de e-commerce la usan para mejorar fotos de productos de vendedores. Muchas subidas son pequeñas o de baja calidad. El escalado automático hace cada anuncio más profesional. Aprende más sobre escalar imágenes sin perder calidad.

Servicios de impresión bajo demanda necesitan archivos de alta resolución. Los clientes suben imágenes que se ven bien en pantalla pero son pequeñas para imprimir. Puedes incluso escalar directamente a 4K.

Apps de restauración de fotos combinan escalado con otras mejoras. Las fotos viejas o borrosas se corrigen y amplían. La API hace el trabajo pesado de IA.

Sistemas de gestión de contenido pueden mejorar imágenes automáticamente al subirlas. Mantienen cada imagen por encima de un estándar mínimo de calidad.

Portales inmobiliarios se benefician de calidad fotográfica uniforme. Los agentes suben con cámaras diferentes. El escalado automático crea una apariencia profesional.

Para procesamiento por lotes, consulta nuestra guía sobre automatizar el escalado de imágenes. También puedes comparar los mejores escaladores.

¿Listo para empezar?

Tendrás una integración funcionando en menos de una hora. Crea tu cuenta en upscaleimg.app, obtén tu clave API y envía tu primera imagen de prueba.

Empieza con escalado 2x en unas pocas imágenes para verificar la calidad. Luego integra en tu pipeline. La guía completa de escalado de imágenes cubre todo lo demás sobre escalado con IA.

El plan gratuito alcanza para probar y construir tu prueba de concepto. Cuando estés listo para 4x y mayor volumen, pasa a un plan de pago.