Image Upscaling API: Developer Integration Guide

Adding image upscaling to your app used to mean training AI models from scratch. That took months and a big GPU budget. With the UpscaleIMG API, you send an image and get back a sharp, upscaled version in seconds.

This guide shows you how to integrate UpscaleIMG into your project. You'll see real code examples, learn the available options, and have a working integration by the end.

What Can the UpscaleIMG API Do?

The UpscaleIMG API uses Real-ESRGAN, a powerful AI model built for image super-resolution. You send a photo, and the AI adds realistic detail as it scales up. Edges stay sharp. Textures look natural. Faces keep their features.

Here's what you get:

• 2x and 4x upscaling with AI-powered detail enhancement
• Custom dimensions if you need a specific output size
• Format conversion between PNG, JPG, and WebP
• Metadata control to strip or keep EXIF data
• Up to 64 megapixels output resolution

The API handles all the AI processing on our servers. No GPU needed on your end. No model setup. Just send an HTTP request and get your result.

How Do You Get Started with the API?

You need an API key to make requests. Here's how to get one:

1. Create an account at upscaleimg.app
2. Go to your dashboard and generate an API key
3. Store the key securely on your server

The API endpoint is:

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

Authentication uses a Bearer token in the Authorization header. Keep your API key on the server side. Never expose it in client-side code or commit it to version control.

Free accounts get 2x upscaling. Subscribers unlock 4x upscaling and custom dimensions up to 4x the original size.

How Do You Upscale Your First Image?

The simplest call takes just an image and a scale factor. Here's a curl example that upscales a photo to 2x:

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

The API returns JSON with details about both the original and upscaled image:

{
  "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://..."
  }
}

The url field gives you a signed download link for the upscaled image. Download it right away since signed URLs expire after a short time.

Here's the same request in 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(`Upscaled to ${data.result.width}x${data.result.height}`);
// Download from data.result.url

And in 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"Upscaled to {data['result']['width']}x{data['result']['height']}")
# Download from data['result']['url']

What Options Does the API Support?

The API accepts several parameters through multipart form data. Here's the full list:

Parameter	Required	Values	Description
image	Yes	File	PNG, JPG, JPEG, or WebP image
scale	Yes*	2 or 4	Upscale factor. *Not needed if using custom dimensions.
customWidth	No	Integer	Target width in pixels (max 4x original)
customHeight	No	Integer	Target height in pixels (max 4x original)
objectFit	No	cover, contain, fill	How to fit the image into custom dimensions. Defaults to cover.
outputFormat	No	jpg, jpeg, png, webp	Output format. Defaults to png.
removeMetadata	No	1 or 0	Strip EXIF data from the output. Defaults to 0 (keep).

Custom dimensions give you precise control. Both customWidth and customHeight are required together. The output can't be smaller than the original or larger than 4x the original (2x for free accounts).

For example, to upscale and resize to exactly 3000x2000 as 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"

The objectFit parameter works like CSS object-fit. Use cover to fill the exact dimensions (may crop). Use contain to fit inside the dimensions (may add padding). Use fill to stretch to the exact size.

How Do You Handle Errors and Rate Limits?

The API returns standard HTTP status codes. Here's what to expect:

Status	Meaning
200	Success. Upscaled image returned.
400	Bad request. Missing image, invalid scale, or dimensions out of range.
401	Invalid or missing API key.
403	Forbidden. Trying to use 4x without a subscription, or CORS error.
429	Rate limited. Too many requests.
500	Server error. Try again.

All error responses include a message:

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

For rate limits, add retry logic with backoff. Here's a simple pattern in JavaScript:

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');
}

Also validate before sending. Check that the file is a supported format (PNG, JPG, WebP). Make sure the output won't exceed 64 megapixels. This saves you API calls and gives users faster feedback.

What Are the Best Use Cases for the UpscaleIMG API?

The API fits naturally into several common workflows.

E-commerce platforms use it to enhance product photos from sellers. Many seller uploads are small or low quality. Auto-upscaling on upload makes every listing look professional. Learn more about upscaling without quality loss.

Print-on-demand services need high-res files for printing. Customers often upload images that look fine on screen but are too small for print. The API bridges that gap. You can even upscale directly to 4K for large format prints.

Photo restoration apps combine upscaling with other fixes. Old or blurry photos get sharpened and enlarged in one step. The API handles the AI work while you build the experience.

Content management systems can auto-enhance images on upload. This keeps every image above a minimum quality bar. Useful for user-generated content where upload quality varies wildly.

Real estate and listing sites benefit from consistent photo quality. Agents upload from phones with varying cameras. Automatic upscaling creates a polished, uniform look across all listings.

For batch processing across many images, check out our guide on how to automate image upscaling. You can also compare different upscaling tools to see how the results stack up.

Ready to Start Building?

You can have a working integration in under an hour. Create your account at upscaleimg.app, grab your API key, and send your first test image.

Start with 2x upscaling on a few sample images to check the quality. Once you're happy, wire it into your pipeline. The complete guide to image upscaling covers everything else you might need to know about AI upscaling in general.

The free tier is enough to test and build your proof of concept. When you're ready to go live with 4x upscaling and higher volumes, upgrade to a paid plan.