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.
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)
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
, orupscale_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 edgesironed_out
– the features and edges are more smoothhigh_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 aspng
,jpg
, orwebp
.
- 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 tofalse
, 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
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__"
}
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 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
{
"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" }
}
}