Upscaler

PRICING

This page describes API for upscaling/super-resolution service for images. The API follows the general rules of Ximilar API as described in Section First steps. We offer two upscaling models - a Classic model that provides good quality upscaling at a lower cost, and a GAN (Generative Adversarial Network) model that produces higher quality results with better details, though at a slightly higher cost.

Activate and try the service in Ximilar App

In order to get access to the Upscaler service, please register at https://app.ximilar.com and then click on this Service on the main panel to make it accessible for your Ximilar account.

Pricing

Pricing of the upscaling service is based on the output (upscaled) image size. For example upscaling 500px image with 2x endpoint costs the same as upscaling 250px image with 4x endpoint, which equals to Upscale XS operation (25-30 credits). In general GAN model (available in output) is providing better outputs, but it is also a bit more expensive. For more information see pricing page.

Asynchronous Upscaling

The upscaler service uses asynchronous requests for processing images because it requires significant GPU resources and is computationally demanding. This means you submit a request and check its status later, allowing for processing of larger images and multiple requests efficiently. The service offers three upscaling factors: 2x, 4x, and 8x.

To use the upscaler service asynchronously, you need to:

1. Submit an upscaling request (optionally with webhook)
2. Store the returned request ID
3. Check the request status (ideally each minute)
4. Retrieve the results when processing is complete

Submitting an Upscaling Request

Required fields for the request:

type: must be "upscaler"
endpoint: one of ["upscale_2x", "upscale_4x", "upscale_8x"]
records: list with one photo to upscale (only one record/photo is possible)
must contain either _url or _base64 field - see section image data for details

Optional parameters:

mode: settings of the upscaling process (default artifact_removal)
- artifact_removal - remove artifacts
- ironed_out - the features and edges are more smooth
- high_fidelity - getting as much details as possible, no post processing (default)
model_type: if not specified classic model will be used
- gan - setting for using generative model (better details but more artificial image)
image_format: if not specified it will try preserve the format of input image data (images with alpha channel will be converted to png, otherwise to jpg). Available options are png, jpg, webp
image_quality: default is 85. Only available when submitting image_format
tune_colors: default is True. Tries to match the color palette of the input image to the upscaled image
webhook: optional endpoint configuration for receiving completion notifications

Curl

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

The JSON response of this request:

CLICK TO SHOW JSON RESULT

Json

{
    "id": "d13389bf-6762-4439-87c6-eb4d02a08bc1",
    "request": {
        "type": "upscaler",
        "model_type": "gan",
        "endpoint": "upscale_2x",
        "records": [
            {
                "_id": "__YOUR_ID__",
                "_url": "__URL_PATH__"
            }
        ],
        "webhook": {
            "endpoint": "__YOUR_POST_URL__",
            "headers": {"optional_field": "optional_value"}
        }
    },
    "type": "upscaler",
    "status": "CREATED",
    "created": "2025-04-12T11:55:23.619492Z",
    "workspace": "82431559-10ea-5d43-98a6-7a1cb38140e3"
}

Getting Results

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

Curl

# List of all requests
curl --request GET \
  --url https://api.ximilar.com/account/v2/request \
  --header 'Authorization: Token __AUTH_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 __AUTH_TOKEN__' \
  --header 'Content-Type: application/json'

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

The completed request response will contain the upscaled image URL in the _upscaled_image_url field:

CLICK TO SHOW JSON RESULT

Json

{
    "id": "d13389bf-6762-4439-87c6-eb4d02a08bc1",
    "created": "2025-04-12T11:55:23.619492Z",
    "modified": "2025-04-12T11:55:32.717459Z",
    "request": {
        "type": "upscaler",
        "records": [
            {
                "_id": "__YOUR_ID__",
                "_url": "__URL_PATH__"
            }
        ],
        "webhook": {
            "endpoint": "__YOUR_POST_URL__",
            "headers": {"optional_field": "optional_value"}
        },
        "endpoint": "upscale_2x",
        "model_type": "gan"
    },
    "response": {
        "records": [
            {
                "_id": "__YOUR_ID__",
                "_url": "__URL_PATH__",
                "_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": "82431559-10ea-5d43-98a6-7a1cb38140e3"
}

Webhook in request

We will send the POST JSON request to the specified endpoint (you can specify it in the webhook field, see upscaler example request above). In this way you will know when to query the results. Your specified endpoint should accept json data that are 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"}
    }
}