Image-Upscaling.net API Documentation

This page describes how to interact with the Image Upscaling, Background Removal, Text-to-Speech, and re-Imagine APIs. The following Python code samples demonstrate how to use these endpoints.

You can copy this code right into your program and test it out (but change the client id). The daily free quota applies to all requests. You can run this code as a notebook here.

Your client id is your secret identifier. Use a random client id to avoid collisions with other users!

1. Setup

First we need a sample image. I highly recommend you use your own sample image because many people submitting the byte-perfect same image could be seen as suspicious and could lead to a ban of your ip.

!wget https://image-upscaling.net/assets/images/test_image.jpg

The client id always should be included in the headers. This is how you identify yourself. You have to use 32 digits, allowed are: 0-9, a-z, A-Z.
Only when downloading results you can also specify the client id as get parameter (?client_id=76..42)

import requests
import json

serverurl = "https://image-upscaling.net"
client_id = "1234567890asdfghjklqwertzUIOPYXC"
cookies = { "client_id": client_id }

2. Upscaling API

Upload an image

You specify the target scale (1,2,3,4), a model (defaults to 'diffuser' for small images, 'plus' for medium large and 'general' for very large images) and any model-specific parameters. See /get_upscalers_config for help.

use_face_enhance = False
scale = 4
path = "test_image.jpg"
model = "general"

url = "/".join([serverurl, "upscaling_upload"])
data = {"scale": scale, "model": model}
if use_face_enhance: # optional param for plus and general models
    data["fx"] = ""
data["prompt"] = "" # optional param for diffuser
data["creativity"] = 0.1 # optional param for diffuser

files = {"image": open(path, "rb")}
original_filename = requests.post(url, data=data, files=files, cookies=cookies).text
print(original_filename)

Get status

All APIs have an endpoint to query the processing status. They will provide you with the download urls.

url = "/".join([serverurl, "upscaling_get_status_v2"]) # or "upscaling_get_status" (old one)
response = requests.get(url, cookies=cookies)
print(response.json())

Download processed files

A good way to download all your result files is to query the processing status and download all images that are marked as complete.
When using ?delete_after_download the server will automatically delete your file after you downloaded it. You can repeat this until there are no more files left.

while True:
  url = "/".join([serverurl, "upscaling_get_status_v2"])
  files = requests.get(url, cookies=cookies).json()

  # download all processed images
  for entry in files:
    filename = entry["filename"]
    completed = entry["completed"]
    url = entry["image_url"]
    if completed:
      original_filename = entry["original_filename"] # this is the filename returned by the upload method, use this to identify your file


      params = {}
      #params["preview"] = "" # will return a small preview
      params["delete_after_download"] = "" # this will delete the file from the server after it was downloaded
      #params["delete_without_download"] = "" # this will delete the file from server but skip returning the file content. Can be used after you already downloaded the file.

      print("downloading", filename)
      response = requests.get(url, cookies=cookies, params = params)
      with open(filename, "wb") as f:
        f.write(response.content)

  if(len(files) == 0):
    break # everything is downloaded
  else:
    import time
    time.sleep(1)

3. Background Removal API

This API is almost the same as the upscaling API, it just has different endpoints and no extra data when uploading a file.

Upload an image

path = "test_image.jpg"
url = "/".join([serverurl, "removebg_upload"])
files = {
        "image": open(path, "rb")
}
original_filename = requests.post(url, files=files, cookies=cookies).text
print(original_filename)

Download results

while True:
  url = "/".join([serverurl, "removebg_get_status_v2"])
  files = requests.get(url, cookies=cookies).json()

  # download all processed images
  for entry in files:
    filename = entry["filename"]
    completed = entry["completed"]
    url = entry["image_url"]
    if completed:
      original_filename = entry["original_filename"] # this is the filename returned by the upload method, use this to identify your file


      params = {}
      params["delete_after_download"] = "" # this will delete the file from the server after it was downloaded
      #params["delete_without_download"] = "" # this will delete the file from server but skip returning the file content. Can be used after you already downloaded the file.

      print("downloading", filename)
      response = requests.get(url, cookies=cookies, params = params)
      with open(filename, "wb") as f:
        f.write(response.content)

  if(len(files) == 0):
    break # everything is downloaded
  else:
    import time
    time.sleep(1)

4. Text-to-Speech API

Submit text

You need to specify:

• the text you want to process (note that there is a 60k character limit for every request)
• the speed you want as float
• the voice you want (you can find the voices on the main tts page on the website)

url = "/".join([serverurl, "tts_submit"])
data = {
    "text": "This is the text to speech api",
    "voice": "am_michael",
    "speed": 1.1
}
response = requests.post(url, json=data, cookies=cookies)
print(response.text)

Download results

This endpoint returns a list of your requests with a download link for the mp3 files. Your file is ready when "result" is not empty.

while True:
    url = "/".join([serverurl, "tts_get_data"])
    response = requests.get(url, cookies=cookies).json()

    for element in response:
        url = element["result"]
        if url != "":
            print(url)
            params = {"delete_after_download": ""}
            content = requests.get(url, params=params, cookies=cookies).content
            with open(url.split("/")[-1] + ".mp3", "wb") as f:
                f.write(content)

    if not response:
        break
    else:
        import time
        time.sleep(1)

5. re-Imagine API

The re-Imagine API allows you to apply various styles to images.

Upload an image for processing

path = "test_image.jpg"
url = "/".join([serverurl, "reImagine_upload"])
files = {"image": open(path, "rb")}
data = {
    "style": "Oil_Painting"  # select the desired style
}
req_id = requests.post(url, files=files, cookies=cookies, data=data).text
print(req_id)
#test_image_2025-09-24_11:44:41.452959.png

Get status and check selected image

## get the status for the current request

url = "/".join([serverurl, "reImagine_get_status"])
entries = requests.get(url, cookies=cookies).json()
for entry in entries:
  if entry['req_id'] == req_id:
    print(entry)
#{'input_image': 'http://test.image-upscaling.net/reImagine_download_data/test_image_2025-09-24_11:44:41.452959.png?get_input_image=True', 'is_completed': False, 'req_id': 'test_image_2025-09-24_11:44:41.452959.png', 'result': ''}

Wait for processing and download result

A helper function to wait for processing to complete and download the result.

import time

def wait_and_download(request_id, filename):
    while True:
        url = "/".join([serverurl, "reImagine_get_status"])
        entries = requests.get(url, cookies=cookies).json()

        for entry in entries:
            if entry['req_id'] == request_id:
                if entry['is_completed'] == True:
                    print("the image is processed")
                    url = entry['result']
                    response = requests.get(url, cookies=cookies)
                    with open(filename, "wb") as f:
                        f.write(response.content)
                    return
        time.sleep(1)

# Usage example
filename = req_id
wait_and_download(req_id, filename)

Display the processed image (optional)

If you're using this in a Jupyter notebook, you can display the result:

import matplotlib.pyplot as plt
import matplotlib.image as mpimg

img = mpimg.imread(filename)
imgplot = plt.imshow(img)
plt.show()

6. Account info

Use this endpoint to get information on your account.

url = "/".join([serverurl, "get_account_info"])
response = requests.get(url, cookies=cookies).json()
print(response)
# {'balance': 361.1489, 'client_id': 'af25d8e9971a747bf55c17195f39757a', 'email': 'marvineckhardt04092003@gmail.com', 'has_free_quota_left': False, 'ip': '35.221.153.79', 'quota_free': 0.2, 'quota_used': 0.3765}
  

7. Bonus: change client id in browser

If you want to change client id in browser, you can use

/account?client_id=xxxxx

with a valid client id and it will make the browser switch to the given client id.
The image-upscaling.net app uses this feature.