How to Upscale Images With the ShortPixel API (cURL, PHP, JavaScript & Python Examples)

Got a folder full of small, blurry product photos? Enlarging one of them by hand is quick. Enlarging a few thousand is a different story.

That’s where an API comes in. With the ShortPixel API, upscaling comes down to adding the upscale parameter to a standard optimization request. Pick 2x, 3x, or 4x, and ShortPixel’s AI model returns a higher-resolution version of the image with improved sharpness.

No worries, it’s nothing complex. We’ll go through it step by step, with ready-to-use examples.

In this article, we’ll look at how to upscale images with the ShortPixel API using cURL, PHP, JavaScript, and Python.

Why upscale images with an API?

You can upscale a single image with our free online tool. But if you’re here, you probably have a bigger job on your hands. Here’s when the API makes sense:

• Low-resolution sources: supplier photos, old archives, or user uploads often arrive smaller than you need them.
• Retina and high-resolution screens: a larger, sharper image looks better on modern displays.
• Bigger formats: hero images, banners, and zoomable product photos need more pixels to work with.
• Automation: if you have hundreds or thousands of images, or new ones coming in all the time, you don’t want to click through them one by one.

What do you need to get started?

Not much. Just two things:

• A ShortPixel API key. You can find it in your ShortPixel dashboard and in the signup confirmation email. If you don’t have an account yet, you can sign up for free.
• Your images. They can be online (available through a URL) or stored on your computer or server.

How does upscaling work in the ShortPixel API?

Upscaling is part of ShortPixel’s Reducer API. It’s the same API that compresses, resizes, and converts your images, and the same one we used to remove image backgrounds with the ShortPixel API. You just add the upscale parameter to the request.

The parameter accepts these values:

• 2: enlarges the image 2x.
• 3: enlarges the image 3x.
• 4: enlarges the image 4x.
• 0: no upscaling (the default).

How much does it cost?

AI Image Upscaling costs 1 AI Credit per image.

And there are three endpoints you can use, depending on where your images are:

• reducer.php: for images that are online. You can send up to 100 URLs in one request.
• reducer-sync.php: also for online images, but it returns the processed image directly instead of a JSON response.
• post-reducer.php: for images stored on your computer or server, which you upload with the request.

1. Upscale an image with cURL

This is the quickest way to test the API. Open your terminal and run:

curl -X POST https://api.shortpixel.com/v2/reducer.php \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_API_KEY",
    "plugin_version": "MY123",
    "lossy": 1,
    "wait": 30,
    "upscale": 4,
    "urllist": ["https://example.com/images/product.jpg"]
  }'

Here’s what the parameters do:

• key: your API key.
• plugin_version: a code you choose for your app (maximum 5 alphanumeric characters).
• lossy: the compression type (1 for lossy, 2 for glossy, 0 for lossless).
• wait: how many seconds (1 to 30) the API should wait for the image to be ready before responding.
• upscale: the enlargement factor, in this case 4x.
• urllist: the list of image URLs to process.

Don’t need such a big jump? Just change the upscale value:

"upscale": 2

Get the image directly with the sync endpoint

If you don’t want to deal with JSON and a second download step, use the synchronous endpoint. It sends back the processed image, so you can save it straight to a file:

curl -X POST https://api.shortpixel.com/v2/reducer-sync.php \
  -H "Content-Type: application/json" \
  -d '{
    "key": "YOUR_API_KEY",
    "plugin_version": "MY123",
    "lossy": 1,
    "upscale": 4,
    "url": "https://example.com/images/product.jpg"
  }' \
  -o product-4x.jpg

Notice that this endpoint takes a single url instead of a urllist.

2. Upscale an image with PHP

Here’s the same request in PHP:

<?php

$apiKey   = 'YOUR_API_KEY';

$endpoint = 'https://api.shortpixel.com/v2/reducer.php';

$data = json_encode([

    'key'            => $apiKey,

    'plugin_version' => 'MY123',

    'lossy'          => 1,

    'wait'           => 30,

    'upscale'        => 4,

    'urllist'        => ['https://example.com/images/product.jpg'],

]);

ch=curlinit(endpoint);

curl_setopt_array($ch, [

    CURLOPT_POST           => true,

    CURLOPT_POSTFIELDS     => $data,

    CURLOPT_HTTPHEADER     => ['Content-Type: application/json', 'Accept: application/json'],

    CURLOPT_RETURNTRANSFER => true,

    CURLOPT_TIMEOUT        => 60,

]);

response=curlexec(ch);

curl_close($ch);

item=jsondecode(response, true)[0];

if ((int) $item['Status']['Code'] === 2) {

    // The image is ready, so we download it

    file_put_contents('product-4x.jpg', file_get_contents($item['LossyURL']));

    echo 'Done!';

} else {

    echo $item['Status']['Code'] . ': ' . $item['Status']['Message'];

}

If you prefer something shorter, ShortPixel also has an official PHP library with a simple, fluent syntax.

3. Upscale an image with JavaScript

Here’s an example using fetch in Node.js (version 18 or newer):

const response = await fetch('https://api.shortpixel.com/v2/reducer.php', {

  method: 'POST',

  headers: {

    'Content-Type': 'application/json',

    'Accept': 'application/json',

  },

  body: JSON.stringify({

    key: 'YOUR_API_KEY',

    plugin_version: 'MY123',

    lossy: 1,

    wait: 30,

    upscale: 4,

    urllist: ['https://example.com/images/product.jpg'],

  }),

});

const [item] = await response.json();

if (Number(item.Status.Code) === 2) {

  console.log('Upscaled image:', item.LossyURL);

} else {

  console.log(`${item.Status.Code}: ${item.Status.Message}`);

}

Important: don’t use your API key in JavaScript that runs in the browser. Anyone can see it in the developer tools. Make the request from your server and send only the result to the browser.

Using Node.js? ShortPixel also has an official Node.js SDK, so you don’t have to build the requests manually. It has a dedicated upscale() helper, and it takes care of polling for you.

import SHORTPIXEL from "@shortpixel-com/shortpixel";

const { ShortPixelClient } = SHORTPIXEL;

const cli = new ShortPixelClient({ apiKey: process.env.SHORTPIXEL_API_KEY });

// Upscale a product photo 2x and also generate a WebP version

const src = await cli.upscale("assets/product.jpg", 2, { convertto: "+webp" });

await src.downloadTo("./output");

Install it with npm i @shortpixel-com/shortpixel. The package is ESM-only, and Node 20+ is recommended.

4. Upscale an image with Python

import requests

r = requests.post(

    'https://api.shortpixel.com/v2/reducer.php',

    json={

        'key': 'YOUR_API_KEY',

        'plugin_version': 'MY123',

        'lossy': 1,

        'wait': 30,

        'upscale': 4,

        'urllist': ['https://example.com/images/product.jpg'],

    }

)

item = r.json()[0]

if int(item['Status']['Code']) == 2:

    img = requests.get(item['LossyURL'])

    with open('product-4x.jpg', 'wb') as f:

        f.write(img.content)

5. Upscale images that aren’t online

What if the image is on your computer or server and doesn’t have a public URL? Then use the post-reducer.phpendpoint and upload the file with your request:

curl -X POST https://api.shortpixel.com/v2/post-reducer.php \

  -F "key=YOUR_API_KEY" \

  -F "plugin_version=MY123" \

  -F "lossy=1" \

  -F "wait=30" \

  -F "upscale=4" \

  -F 'file_paths={"file1": "/unique/path/product.jpg"}' \

  -F "file1=@product.jpg"

The file_paths parameter tells the API which file is which. The key (here, file1) must be the same as the name of the uploaded file field. The value can be any string, as long as it’s unique to that file.

Understanding the API response

The API sends back a JSON response with one entry for each image. The most important field is Status, which has a Code and a Message:

• Code 2: the image is processed, and the download link is in the response.
• Code 1: the image was scheduled for processing, but it’s not ready yet. Send the same request again after a few seconds.

Upscaling is more demanding than regular compression, so it can take longer, especially with a 4x factor. Seeing code 1 from time to time is normal. Just send the same request again after a few seconds.

If you uploaded a file with post-reducer.php and got code 1, don’t upload it again, as it would be processed as a new image. Instead, call reducer.php with the OriginalURL from the first response to check the status.

These are the errors you’re most likely to see:

• -401 / -402: invalid API key.
• -403: your quota is exceeded. You’ll need a bigger plan or an additional package.
• -106: the image URL can’t be accessed by ShortPixel’s servers.
• -111: the file is too big.
• -205: the file’s width and/or height is too big.
• -404: the optimization queue is full. Try again in a minute.

You’ll find the full list in the API documentation.

A few tips for working with many images

• Send images in batches. With reducer.php you can process up to 100 URLs in a single request.
• Use different settings for different images. The paramlist parameter lets you set custom options for each URL in the same request, for example 2x for one image and 4x for another.
• Replaced an image but kept the same URL? Add “refresh”: 1 so ShortPixel downloads and processes it again. Otherwise, you may get the previously processed version.
• Combine tasks. You can upscale, convert to WebP or AVIF, and remove the background in a single request. For example, add “bg_remove”: “1” next to “upscale”: 4 to get an enlarged image with a transparent background.
• Keep track of your images. Anything you add to returndatalist comes back unchanged in the response, so you can easily match the results with your own data (a product ID, for example).

Is upscaling always a good idea?

Not always. It depends on the source image and what you need it for.

AI upscaling can make images look sharper and cleaner, but it can’t recover every detail that was missing from the original. A small, clean source usually gives better results than a tiny, heavily compressed image.

Also, a bigger image means a bigger file. That’s why it makes sense to combine upscaling with compression (the lossyparameter) and, for websites, with WebP or AVIF conversion (convertto). You get the extra resolution without slowing your pages down.

Conclusion

Upscaling doesn’t have to be a manual job. With the upscale parameter, a single API request does it for you, whether you have one image or thousands.

Pick the example that fits your project, add your API key, and you’re ready to go. And once your images are sharp, you can use the same API to resize, compress, convert, or remove their backgrounds.

Want to see the results before writing any code? Try the free online image upscaler. And if you’re still deciding which service to use, compare the most popular image upscaling APIs with PHP examples.

FAQs