Upscaler

Quickstart Blog Test in APP Public Demo

In order to get access to the Upscaler service, please register at https://app.ximilar.com. In the app pick "Ready-To-Use Image Recognition" on the main dashboard and then Upscaler. This service is available in all pricing plans. A public demo is located at demo.ximilar.com.

This page describes API of Upscaler service for images. With this service you can upscale/super-resolution images via AI. The API offers 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.

This service uses asynchronous API with webhook - because upscaling requires significant GPU resources and is computationally demanding. You submit a request and check its status later, allowing for processing of larger images and multiple requests efficiently.

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.

Endpoints

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

https://api.ximilar.com/account/v2/request               (for submitting upscaling requests)
https://api.ximilar.com/account/v2/request/{id}          (for retrieving specific result)
https://api.ximilar.com/account/v2/request/{id}/status   (for checking status of request)

POST/v2/request

Upscaling Request

Quickstart

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

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.

Required attributes

Name
type
Type
string
Description
Must be "upscaler"
Name
endpoint
Type
string
Description
One of ["upscale_2x", "upscale_4x", "upscale_8x"]
Name
records
Type
dict
Description
A list with one photo to upscale (only one record/photo is possible), defined by _url or _base64.

Optional attributes

Name
mode
Type
string
Default
Default:artifact_removal
Description
Settings of the upscaling process:
- 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)
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 more artificial image)
Name
image_format
Type
string
Default
Default:auto
Description
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
Name
image_quality
Type
integer
Default
Default:85
Description
Default is 85. Only available when submitting image_format
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
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

Quickstart

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 the endpoints below.

Required attributes

Name
id
Type
string
Description
The unique identifier for 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 for 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 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" }
  }
}