Image Upscaler

Quickstart Blog Test in APP Public Demo

This page describes the API for the Image Upscaler service. With this solution, you can upscale images in bulk using AI-powered super-resolution. The API supports two upscaling models, specified via the model_type parameter:

The Classic model offers good quality results at a lower cost.
The GAN (Generative Adversarial Network) model delivers higher-quality upscaling with improved detail, at a slightly higher cost.

To access the Image Upscaler API, please register at https://app.ximilar.com. This service is available in all pricing plans. A public demo is also available at https://demo.ximilar.com.

This service uses an asynchronous API, as upscaling is GPU-intensive and computationally demanding. You submit a request and check its status later, allowing efficient processing of larger images and multiple requests. A webhook is optional and can be enabled to receive automatic status updates – otherwise, you’ll need to poll the status manually.

Pricing of the upscaling service is based on the output (upscaled) image size. For example, upscaling a 500px image 2x costs the same as upscaling 250px image 4x, both of which equals to Upscale XS operation (25–30 credits). In general, the GAN model provides better outputs, but it also demands more API credits.

Endpoints

This service API has several endpoints running at URLs, each of them suitable for different use case:

https://api.ximilar.com/account/v2/request               (submit an upscaling request)
https://api.ximilar.com/account/v2/request/{id}          (retrieve the result of a specific request)
https://api.ximilar.com/account/v2/request/{id}/status   (check the status of a specific request)

POST/v2/request

Upscaling Request

Both the Classic and GAN models support upscaling to 2x, 4x, and 8x and are called via this endpoint. You need to distinguish it via optional parameter type and endpoint.

Given a single image record, this method submits an upscaling request for processing. The service offers three upscaling factors: 2x, 4x, and 8x.

This is an asynchronous API, designed to efficiently handle GPU-intensive upscaling tasks. You submit a request and check the status later. A webhook is optional and can be enabled to receive completion notifications.

Required attributes

Name
type
Type
string
Description
Must be upscaler.
Name
endpoint
Type
string
Description
Must be either upscale_2x, upscale_4x, or upscale_8x.
Name
records
Type
dict
Description
The input is a list, but must contain exactly one image per request. The image should be provided using either _url or _base64.

Optional attributes

Name
mode
Type
string
Default
Default:artifact_removal
Description
Controls the upscaling style:
- artifact_removal – smooths features and edges
- ironed_out – the features and edges are more smooth
- high_fidelity – preserves maximum detail, no post-processing (default setup)
Name
model_type
Type
string
Default
Default:classic
Description
If not specified, Classic model will be used.
- gan – setting for using generative model (better details, but the resulting image may seem more artificial).
Name
image_format
Type
string
Default
Default:auto
Description
If not specified, the system will try to preserve the format of the input image data (only images with alpha channels will be converted to png). You can specify the output format as png, jpg, or webp.
Name
image_quality
Type
integer
Default
Default:85
Description
Default is 85. Max is 100. Only available when submitting image_format. The higher the value, the more conservative will the JPEG/PNG encoder be when discarding image information. This results in an image that is visually very close to the original.
Name
tune_colors
Type
boolean
Default
Default:True
Description
Default is true. Tries to match the color palette of the input image to the upscaled image. If set to false, the colors will be determined by the AI upscaling model.
Name
webhook
Type
dict
Default
Default:null
Description
Optional endpoint configuration for receiving completion notifications.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. Body of the response is a JSON object (map) with the following fields:

Name
id
Type
string
Description
The unique identifier for the request.
Name
request
Type
dict
Description
The original request data.
Name
type
Type
string
Description
The type of request ("upscaler").
Name
status
Type
string
Description
The status of the request ("CREATED").
Name
created
Type
string
Description
The timestamp when the request was created.
Name
workspace
Type
string
Description
The workspace identifier.

Request

POST

/v2/request

curl --request POST \
  --url https://api.ximilar.com/account/v2/request \
  --header 'Authorization: Token __API_TOKEN__' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "upscaler",
    "endpoint": "upscale_2x",
    "model_type": "gan",
    "records": [
        { "_url": "__PATH_TO_IMAGE_URL__" }
    ],
    "webhook": {
        "endpoint": "__YOUR_POST_URL__",
        "headers": {"optional_field": "optional_value"}
    }
}'

Response

{
  "id": "d13389bf-6762-4439-87c6-eb4d02a08bc1",
  "request": {
    "type": "upscaler",
    "model_type": "gan",
    "endpoint": "upscale_2x",
    "records": [
      {
        "_url": "__PATH_TO_IMAGE_URL__"
      }
    ],
    "webhook": {
      "endpoint": "__YOUR_POST_URL__",
      "headers": { "optional_field": "optional_value" }
    }
  },
  "type": "upscaler",
  "status": "CREATED",
  "created": "2025-04-12T11:55:23.619492Z",
  "workspace": "__WORKSPACE_ID__"
}

GET/v2/request/{id}

Getting Results

You can use this endpoint to get the result of a specific request or to check the status of a request.

The upscaled image URL will be available in the response once the processing is complete. The URL will be valid for 24 hours. You can check the status and get results using the endpoints below.

Required attributes

Name
id
Type
string
Description
The unique identifier of the request.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. Body of the response is a JSON object (map) with the following fields:

Name
id
Type
string
Description
The unique identifier of the request.
Name
created
Type
string
Description
The timestamp when the request was created.
Name
modified
Type
string
Description
The timestamp when the request was last modified.
Name
request
Type
dict
Description
The original request data.
Name
response
Type
dict
Description
The response data containing the upscaled image URL.
Name
type
Type
string
Description
The type of request ("upscaler").
Name
status
Type
string
Description
The status of the request ("DONE").
Name
workspace
Type
string
Description
The workspace identifier.

Request

GET

/v2/request/{id}

# Get result of specific request
curl --request GET \
  --url https://api.ximilar.com/account/v2/request/__REQUEST_ID__ \
  --header 'Authorization: Token __API_TOKEN__' \
  --header 'Content-Type: application/json'

# Check status of specific request
curl --request GET \
  --url https://api.ximilar.com/account/v2/request/__REQUEST_ID__/status \
  --header 'Authorization: Token __API_TOKEN__' \
  --header 'Content-Type: application/json'

# List of all requests
curl --request GET \
  --url https://api.ximilar.com/account/v2/request \
  --header 'Authorization: Token __API_TOKEN__' \
  --header 'Content-Type: application/json'

Response

GET

/v2/request/{id}

{
  "id": "d13389bf-6762-4439-87c6-eb4d02a08bc1",
  "created": "2025-04-12T11:55:23.619492Z",
  "modified": "2025-04-12T11:55:32.717459Z",
  "request": {
    "type": "upscaler",
    "records": [
      {
        "_url": "__PATH_TO_IMAGE_URL__"
      }
    ],
    "webhook": {
      "endpoint": "__YOUR_POST_URL__",
      "headers": { "optional_field": "optional_value" }
    },
    "endpoint": "upscale_2x",
    "model_type": "gan"
  },
  "response": {
    "records": [
      {
        "_url": "__PATH_TO_IMAGE_URL__",
        "_width": 212,
        "_height": 174,
        "_status": {
          "code": 200,
          "text": "OK",
          "request_id": "d15389bf-6762-4439-87c6-eb4d02a08bc1"
        },
        "_upscaled_width": 424,
        "_upscaled_height": 348,
        "_upscaled_image_url": "__URL_PATH_UPSCALED__"
      }
    ]
  },
  "type": "upscaler",
  "status": "DONE",
  "workspace": "__WORKSPACE_ID__"
}

Webhook Configuration

When you specify a webhook in your request, we will send a POST JSON request to the specified endpoint when the processing is complete. Your specified endpoint should accept JSON data in this format:

{
  "status": "DONE",
  "id": "__ASYNC_REQUEST_ID__",
  "type": "upscaler",
  "response": {
    "records": [
      {
        "_id": "__RECORD_ID__",
        "_url": "__ORIGINAL_URL_PATH__",
        "_width": WIDTH,
        "_height": HEIGHT,
        "_status": {
          "code": 200,
          "text": "OK",
          "request_id": "__REQUEST_ID__"
        },
        "_upscaled_width": UPSCALED_WIDTH,
        "_upscaled_height": UPSCALED_HEIGHT,
        "_upscaled_image_url": "__UPSCALED_URL_PATH__"
      }
    ]
  }
}

You can specify your custom headers (optional) that will be sent to the endpoint. The webhook is specified inside the data of the asynchronous request:

{
  "type": "upscaler",
  "endpoint": "upscale_2x",
  "records": [
    {
      "_url": "__URL_PATH__"
    }
  ],
  "webhook": {
    "endpoint": "__YOUR_POST_URL__",
    "headers": { "optional_field": "optional_value" }
  }
}