Image Optimization API

URL to call: https://api.shortpixel.com/v2/reducer.php

{"key": "your api key", "plugin_version": "MY123", "lossy": 1, "resize": 1, "resize_width": 1024, "resize_height": 1024, "cmyk2rgb": 1, "keep_exif": 0, "convertto": "+webp", "refresh": 0, "urllist": ["url1", "url2"]}

JSON Encoded parameters, as follows

• key - Your API key.
• plugin_version - Your API client identifier (choose it yourself)
• lossy - 1 if we should compress the images (files) in a lossy way, 2 for glossy compression, 0 for lossless
• wait - maximum time to wait for the optimization to be ready
• resize - type of resize
• resize_width - resize width in pixels
• resize_height - resize height in pixels
• cmyk2rgb - convert CMYK to RGB
• keep_exif - keep the EXIF info of the file
• convertto - conversion to other image formats
• bg_remove - background removal
• refresh - download the image again from source
• urllist - list of image URLs to optimize
• paramlist - list of optimization parameters for the URLs (not required)
• returndatalist - any array can be sent and it will be returned in the API response

Your API key, as provided in your ShortPixel control panel and signup confirmation email.

5 chars max., alphanumeric. Choose a code for your API client (MY123, RR007 for a Ruby on Rails client, etc.).

Controls whether the image compression will use a lossy or lossless algorithm.

• 1 - Lossy compression. Lossy has a better compression rate than lossless compression. The resulting image is not 100% identical with the original. Works well for photos taken with your camera.
• 2 - Glossy compression. Creates images that are almost pixel-perfect identical to the originals. Best option for photographers and other professionals that use very high quality images on their sites and want best compression while keeping the quality untouched.
• 0 - Lossless compression. The shrunk image will be identical with the original and smaller in size. Use this when you do not want to loose any of the original image's details. Works best for technical drawings, clip art and comics.

{wait}

Set it between 1 and 30 to wait for that number of seconds for the conversion to be done before the API returns, 0 to return immediately. If the optimization is not done in the given amount of wait time, Code 1 (see below) is returned and you can just redo the same post later to find out if the image is ready.

{resize}

The type of resizing applied to the image.

• 0 - no resizing, the current size is preserved.
• 1 - outer resizing (image will contain the given resize_width x resize_height rectangle).
• 3 - means inner resizing (image will be contained in the given resize_width x resize_height rectangle).
• 4 - smart cropping using AI

{resize_width}

The width in pixels for the resize. Needed only if resize > 1.

{resize_height}

The height in pixels for the resize. Needed only if resize > 1.

{cmyk2rgb}

Convert CMYK to RGB, default is set to 1. Images for the web only need RGB format and converting them from CMYK to RGB makes them smaller.

{keep_exif}

Keep the EXIF tag of the image. Default is set to 0, meaning the EXIF tag is removed.

{convertto}

Convert also to other image types, when optimizing.
For converting to WebP use "+webp", for converting to AVIF use "+avif". "+" means that the original image will be also optimized, if "+" is missing then the original format won't be touched.
If you want to convert to both .webp and .avif and also optimize the original image please use "+webp|+avif".
If you just want to convert to both .webp and .avif then use "webp|avif".
It is also possible to convert images from jpeg, png, gif, bmp and tiff to jpeg, png or gif. Just use "jpg", "png" or "gif" to select to what format you want to convert. Leave it empty if no conversion is needed.

{bg_remove}

Posible values

• 1 - transparent.
• URL - URL of an image to be used as background.
• #rrggbbxx rrggbb = hexadecimal background color code, xx = transparency level (00 full transparency,FF no transparency).

{refresh}

If refresh is set to 1, the image is fetched again by our servers from the source and re-optimized. Otherwise, if the image is already optimized and still available on our servers, the currently optimized image info is returned.

{urllist}

The list of URLs where the original image is located. They need to be valid, maximum 100 URLs are allowed.

{paramlist}

If this field is not defined, then the default parameters will be used. If defined, it needs to be an array with the same number of lines as the URLs sent to be optimized. Each line contains the custom optimization parameters for each of the URLs.
Example:
array
(
"https://shortpixel.com/img/tests/beautiful-woman.jpg",
"https://shortpixel.com/img/tests/beautiful-woman.jpg",
"https://shortpixel.com/img/tests/beautiful-woman.jpg",
"https://shortpixel.com/img/tests/beautiful-woman.jpg",
);

array
(
['resize' => 4, 'resize_width' => 400, 'resize_height' => 300, 'convertto' => '+webp'],
['resize' => 4, 'resize_width' => 100, 'resize_height' => 100, 'convertto' => '+avif|+webp'],
['resize' => 3, 'resize_width' => 200, 'resize_height' => 200, 'convertto' => 'webp'],
['resize' => 4, 'resize_width' => 250, 'resize_height' => 250],
);

{returndatalist}

This field can be left empty or it can contain any type of array. If an array is defined, then it will be returned unchanged, in the API response.

• Code - This is a numeric code identifying the outcome of the call. Can be:
  • 1 - No errors, image scheduled for processing.
  • 2 - No errors, image processed, download URL available.
  • -102 - Invalid URL. Please make sure the URL is properly urlencoded and points to a valid image file.
  • -105 - URL is missing for the call.
  • -106 - URL is inaccessible from our server(s) due to access restrictions.
  • -107 - Too many URLs in a POST, maximum allowed has been exceeded.
  • -108 - Invalid user used for optimizing images from a particular domain.
  • -109 - Please use reducer.php endpoint for URL optimizations.
  • -113 - Too many inaccessible URLs from the same domain, please check accessibility and try again.
  • -114 - Please provide the local file paths of the optimized images.
  • -115 - Uploaded files are missing.
  • -116 - The number of URL parameters needs to be equal with the number of URLs.
  • -201 - Invalid image format.
  • -202 - Invalid image or unsupported image format.
  • -203 - Could not download file.
  • -204 - The file couldn't be optimized, possibly timedout.
  • -205 - The file's width and/or height is too big.
  • -206 - The PDF file is password protected and it cannot be optimized.
  • -207 - Invalid parameters for background removal.
  • -301 - The file is larger than the remaining quota.
  • -302 - The file is no longer available.
  • -303 - Internal API error: the file was not written on disk.
  • -305 - Internal API error: Unknown, details usually in message.
  • -306 - Files need to be from a single domain per request.
  • -401 - Invalid API key. Please check that the API key is the one provided to you.
  • -403 - Quota exceeded. You need to subscribe to a larger plan or to buy an additional one time package to increase your quota.
  • -404 - The maximum number of URLs in the optimization queue reached. Please try again in a minute.
  • -500 - API is in maintenance mode. Please come back later.
• Message - A text message explaining what the code stands for.

$URL = "https://api.shortpixel.com/v2/reducer.php";
$APIKey = "<<YOUR API KEY HERE>>";
$Lossy = "1";
$Resize = "0";
$ImagesList = array(
    "http://<<FULL URL OF THE IMAGE1>>",
    "http://<<FULL URL OF THE IMAGE2>>"
);
$ImagesList = array_map('rawurlencode', $ImagesList);
$Data = json_encode(array(
    "plugin_version" => "XY123", //5 chars max - choose a code for your app
    "key" => $APIKey,
    "lossy" => $Lossy,
    "urllist" => $ImagesList
));
$POSTArray = array(
    'http' => array(
        'method' => 'POST',
        'header' => "Content-Type: application/json\r\n" . "Accept: application/json\r\n" . "Content-Length: " . strlen($Data) ,
        'content' => $Data
    )
);
$Context = stream_context_create($POSTArray);
$Result = file_get_contents($URL, false, $Context);
                

$.post('https://api.shortpixel.com/v2/reducer.php',JSON.stringify({
    "key": "<<YOUR_KEY_HERE>>",
    "plugin_version": "JS123",
    "lossy": 1,
    "resize": 0,
    "cmyk2rgb": 1,
    "refresh": 0,
    "urllist": ["https://www.your.domain/first/image.jpg", "https://www.your.domain/second/image.jpg"]
}), function (data) {
    alert('success');
});
              

JavaScriptSerializer js = new JavaScriptSerializer();
var data = new Dictionary
           {
               { "key", "<<YOUR_KEY_HERE>>" },
               { "plugin_version", "CS123" },
               { "lossy", "1" },
               { "resize", "0" },
               { "cmyk2rgb", "1" },
               { "urllist", new String[] {"https://www.your.domain/first/image.jpg", "https://www.your.domain/second/image.jpg"} }
           };
string formData = js.Serialize(keyValues);
Console.WriteLine ("formData");

byte[] postData = Encoding.UTF8.GetBytes(formData);

Uri uRI = new Uri("https://api.shortpixel.com/v2/reducer.php");
HttpWebRequest request = WebRequest.Create(uRI) as HttpWebRequest;

Encoding myEncoding = Encoding.UTF8;
request.Method = "POST";
request.ContentType = "application/x-www-form-urlencoded";
request.KeepAlive = true;
request.AllowAutoRedirect = true;
request.ContentLength = postData.Length;

Stream outputStream = request.GetRequestStream();
outputStream.Write(postData, 0, postData.Length);
outputStream.Close();

HttpWebResponse res = request.GetResponse() as HttpWebResponse;
Stream inStream = res.GetResponseStream();
StreamReader reader = new StreamReader(inStream, Encoding.UTF8);
string dataResult = reader.ReadToEnd();

reader.Close();
inStream.Close();
              

import requests
import json
from pprint import pprint
image_path ='https://some.image/url.jpg'
sp_key = '<<YOUR_KEY_HERE>>'
r = requests.post(
    url='https://api.shortpixel.com/v2/reducer.php',
    data=json.dumps({'key': sp_key, 'lossy': 1, 'wait': 20, 'urllist':[image_path]})
)
pprint(r.json())
              

URL to call: https://api.shortpixel.com/v2/post-reducer.php

The parameters are the same as for the Reducer API except the urllist that is replaced by either file_paths and the posted files, or file_urls.

• file_paths - the local file full paths. These are mainly used to be included in the reporting of the optimized images, for identification (as there is no client URL of the image). If the image is stored in a temporary location, please make up some unique path which is relevant to you, for that image. These paths should be a key:value array where the key is equal to the 'name' parameter of the corresponding uploaded file.
• file_urls - the corresponding OriginalURLs. These URLs are returned by the first call to post-reducer and they are temporary URLs available while the image is being optimized. If an image is not ready and returns pending after the first call, you should not re-upload it, but pass the OriginalURL inside this array in subsequent calls so the Post-Reducer API just checks the status and returns the results. If the file is re-uploaded, it will be put to optimization as a new file.

The parameters are sent as a multipart POST request, as in the following example (for PHP, see below a code snippet that generates a multipart POST request):

/
User-Agent: curl/7.21.2 (x86_64-apple-darwin)
Host: localhost:8080
Accept: */*
Content-Length: 1143
Expect: 100-continue
Content-Type: multipart/form-data; boundary=----------------------------83ff53821b7c

------------------------------83ff53821b7c
Content-Disposition: form-data; name="key"

YOUR_20_CHARS_APIKEY
------------------------------83ff53821b7c--
Content-Disposition: form-data; name="lossy"

1
------------------------------83ff53821b7c--
Content-Disposition: form-data; name="file_paths"

{"file1": "/the/file1/path/a.png"}
------------------------------83ff53821b7c--
Content-Disposition: form-data; name="file1"; filename="a.png"
Content-Type: application/octet-stream

?PNG FILE CONTENTS HERE.....?
------------------------------83ff53821b7c
            

The local file full paths as a json-encoded key-value array where the key is the same as the name of the file sent (file1 ...). You can provide any string for the value, but it should be unique to the file sent.

The corresponding OriginalURLs sent by the API as answer to a previous call for the same filename. Please provide only either file_paths or file_urls.

• Code - This is a numeric code identifying the outcome of the call. On top of the codes above, it can be:
  • -109 - The uploaded files are not present. If the urllist is present instead, the message asks to use the Reducer API URL. The error will also be returned in case neither file_paths nor file_urls parameter is present
  • -110 - Upload error
  • -111 - File too big
  • -112 - Generic server error (details in the message field)
  • -115 - Uploaded files are missing.
  • -117 - Please pass the file_paths parameter as per the API specs.
  • -304 - Internal API Error - could not create user upload space. Please contact support if you encounter this error
• Message - A text message explaining what the code stands for

<?php
$URL = "https://api.shortpixel.com/v2/post-reducer.php";
$curl = curl_version();
$userAgent = "ShortPixel/1.0 " . " curl/" . $curl["version"];
$request = curl_init();
curl_setopt($request, CURLOPT_URL, $URL);
curl_setopt_array($request, array(
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_BINARYTRANSFER => true,
    CURLOPT_HEADER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_SSL_VERIFYPEER => false,
    CURLOPT_SSL_VERIFYHOST => false,
    CURLOPT_USERAGENT => $userAgent,
));
$files = array(
    "file1" => "/path/to/first/file.jpg",
    "file2" => "/path/to/second/file.png"
);
$options = array(
    "key" => YOUR_SHORTPIXEL_API_KEY,
    "lossy" => 1,
    "file_paths" => json_encode($files)
);
curl_custom_postfields($request, $options, $files);
$response = curl_exec($request);
curl_close($request);

function curl_custom_postfields($ch, array $assoc = array() , array $files = array() , $header = array()) {
    // invalid characters for "name" and "filename"
    static $disallow = array(
        "\0",
        "\"",
        "\r",
        "\n"
    );
    // build normal parameters
    foreach ($assoc as $k => $v) {
        $k = str_replace($disallow, "_", $k);
        $body[] = implode("\r\n", array(
            "Content-Disposition: form-data; name=\"{$k}\"",
            "",
            filter_var($v) ,
        ));
    }
    // build file parameters
    foreach ($files as $k => $v) {
        switch (true) {
            case false === $v = realpath(filter_var($v)):
            case !is_file($v):
            case !is_readable($v):
                continue; // or return false, throw new InvalidArgumentException

        }
        $data = file_get_contents($v);
        $val = explode(DIRECTORY_SEPARATOR, $v);
        $v = end( $val);
        $k = str_replace($disallow, "_", $k);
        $v = str_replace($disallow, "_", $v);
        $body[] = implode("\r\n", array(
            "Content-Disposition: form-data; name=\"{$k}\"; filename=\"{$v}\"",
            "Content-Type: application/octet-stream",
            "",
            $data,
        ));
    }
    // generate safe boundary
    do {
        $boundary = "---------------------" . md5(mt_rand() . microtime());
    } while (preg_grep("/{$boundary}/", $body));
    // add boundary for each parameters
    array_walk($body, function (&$part) use ($boundary) {
        $part = "--{$boundary}\r\n{$part}";
    });
    // add final boundary
    $body[] = "--{$boundary}--";
    $body[] = "";
    // set options
    return @curl_setopt_array($ch, array(
        CURLOPT_POST => true,
        CURLOPT_BINARYTRANSFER => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POSTFIELDS => implode("\r\n", $body) ,
        CURLOPT_HTTPHEADER => array_merge(array(
            "Expect: 100-continue",
            "Content-Type: multipart/form-data; boundary={$boundary}", // change Content-Type

        ) , $header) ,
    ));
}
              

Public Class shortPixelObject
    Public Property Status As shortPixelStatus
    Public Property OriginalURL As String = String.Empty
    Public Property LossyURL As String = String.Empty
    Public Property LosslessURL As String = String.Empty
    Public Property OriginalSize As Integer = 0
    Public Property LossySize As Integer = 0
    Public Property LoselessSize As Integer = 0
    Public Property Timestamp As String = String.Empty
    Public Property Key As String = String.Empty
    Public Property localPath As String = String.Empty
End Class



Private Function postShortPixel(ByVal fileStream As Stream, filename As String, Optional intHeight As Integer = 0, Optional intWith As Integer = 0) As System.IO.Stream
    Dim objResponse() As shortPixelObject
    Try
        Dim strURL As String = FunGlob.AppsettingsSACS.GetKey("ShortPixel.URL")
        Dim strAPI As String = FunGlob.AppsettingsSACS.GetKey("ShortPixel.API")
        Dim blnLossy As Boolean = (FunGlob.AppsettingsSACS.GetKey("ShortPixel.Lossy") = "1")
        Dim wait As Integer = 15

        Integer.TryParse(FunGlob.AppsettingsSACS.GetKey("ShortPixel.Wait"), wait)
        If wait = 0 Then wait = 15

        Dim imageBytesContent As HttpContent = New ByteArrayContent(imgToByteArray(fileStream))
        imageBytesContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/octet-stream")

        Using client As HttpClient = New HttpClient()
            client.DefaultRequestHeaders.Accept.Clear()

            Using formData = New MultipartFormDataContent()
                formData.Add(New StringContent(strAPI), "key")
                formData.Add(New StringContent("MY123"), "plugin_version")
                If blnLossy Then
                    formData.Add(New StringContent("1"), "lossy")
                Else
                    formData.Add(New StringContent("0"), "lossy")
                End If
                formData.Add(New StringContent(wait), "wait")
                If intHeight > 0 Or intWith > 0 Then
                    formData.Add(New StringContent("1"), "resize")
                    If intHeight > 0 Then
                        formData.Add(New StringContent(intHeight), "resize_height")
                    End If
                    If intWith > 0 Then
                        formData.Add(New StringContent(intWith), "resize_width")
                    End If
                Else
                    formData.Add(New StringContent(0), "resize")
                End If
                formData.Add(New StringContent("{""file1"": """ & filename & """}"), "file_paths")
                formData.Add(imageBytesContent, "file1", filename)

                Dim response = client.PostAsync(strURL, formData).Result
                Dim responseContent = response.Content.ReadAsStringAsync().Result

                If Not responseContent Is Nothing Then
                    objResponse = JsonConvert.DeserializeObject(Of shortPixelObject())(responseContent)

                    If Not objResponse Is Nothing AndAlso objResponse.Length > 0 Then
                        If (objResponse(0).Status.Code = 1 Or objResponse(0).Status.Code = 2) Then
                            If objResponse(0).Status.Code = 2 And Len(objResponse(0).LossyURL) > 0 Then
                                Using webClient As WebClient = New WebClient()
                                    Dim imageBytes As Byte() = webClient.DownloadData(objResponse(0).LossyURL)
                                    If imageBytes.Length > 0 Then
                                        Return New MemoryStream(imageBytes)
                                    End If
                                End Using
                            Else
                                Return Nothing
                            End If
                        Else
                            Return Nothing
                        End If
                    Else
                        Return Nothing
                    End If
                Else
                    Return Nothing
                End If
            End Using
        End Using
    Catch ex As Exception
        Return Nothing
    End Try

    Return Nothing

End Function
                

Code example courtesy of Marco Flores

import requests
import json
import os

# Change here with your API key
sp_key = '<<YOUR_KEY_HERE>>'
# Local path to the image you want to compress
image_path = 'image.jpg'

# Send the request to ShortPixel API. Notice the json.dumps function, which is used to encode the
# file_paths parameter - otherwise Python sends an invalid JSON with single quotes instead of double.
r = requests.post(
    url='https://api.shortpixel.com/v2/post-reducer.php',
    files={'my-image': open(image_path, 'rb')},
    data={'key': sp_key, 'lossy': 1, 'refresh': 0, 'wait': 30,
          'file_paths': json.dumps({"my-image": "/local/path/to/image.jpg"}) }
)

# Get the JSON-encoded optimization metadata from the response.
meta = r.json()[0]

# Check wether the image URL is available, and then download the image and save.
if (('LossyURL' in meta.keys() and meta['LossyURL']) and int(meta['Status']['Code']) == 2):
   os.system("wget --method=POST -O %s %s" % ('optimized-image.jpg', meta['LossyURL']))
              

image_path ='https://the.returned/OriginalURL' // for example: http://api.shortpixel.com/u/Ha0BIUk8GRaOMTWVuPWGOtAAPhfRM0z9qBARc6BY/cd9895da43c53d6ef67cba5c44129a63.jpg
sp_key = '<<YOUR_KEY_HERE>>'
r = requests.post(
url='https://api.shortpixel.com/v2/reducer.php',
data=json.dumps({'key': sp_key, 'lossy': 1, 'wait': 20, 'urllist':[image_path]})
)