Image Upscaler

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.

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.

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" }
  }
}

Was this page helpful?