Asynchronous Requests

Quickstart SDKs Test in App

This page explains how to use asynchronous requests to process large batches of images efficiently. You can submit multiple requests simultaneously for background processing. The API includes endpoints to submit requests, check their status, and retrieve results once processing is complete.

If you need to process millions of requests daily or monthly and don’t require immediate results, asynchronous requests with webhooks are the ideal solution.

Supported Services

The following services support asynchronous processing:

Endpoints

There are several endpoints for asynchronous requests:

https://api.ximilar.com/account/v2/request/               (for submitting new requests)
https://api.ximilar.com/account/v2/request/__ID__         (for getting request details)
https://api.ximilar.com/account/v2/request/__ID__/status  (for checking request status)

POST/v2/request

Submit Request

Quickstart

Each request receives a unique ID (UUID) and is stored with the state CREATED. When a worker begins processing, the state changes to PROCESSING. Once completed, the request state updates to DONE.

Required attributes

Name
type
Type
string
Description
Type of the request. Can be:
- upscaler
- flows
- collectibles-recognition
- card-grader
Name
records
Type
array
Description
A batch of JSON records (maximum 10). Each record represents one image and must include either _url or _base64 field.

Optional attributes

Name
webhook
Type
object
Description
Optional webhook configuration containing an endpoint (URL) and optional headers. Used to notify your server (by calling specific endpoint) when the request status changes to DONE.
Name
endpoint
Type
string
Description
Service-specific endpoint (e.g. upscale_2x for upscaler, grade for card-grader)

Returns

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

Name
id
Type
string
Description
Unique identifier of the request.
Name
status
Type
string
Description
Current status of the request (CREATED, PROCESSING, DONE).
Name
type
Type
string
Description
Type of the request.
Name
created
Type
string
Description
Timestamp when the request was created, in ISO 8601 format (e.g., 2022-03-02T13:38:22.784359Z), including date, time, and timezone.
Name
workspace
Type
string
Description
Workspace identifier.

Request

POST

/v2/request

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

Response

{
  "id": "2e9b43f2-61be-4aaa-8a6a-a74fc0f80b57",
  "request": {
    "type": "upscaler",
    "endpoint": "upscale_2x",
    "records": [
      {
        "_url": "https://images.ximilar.com/examples/fashion_products/01_1149810256_SI_00.jpeg"
      }
    ]
  },
  "type": "upscaler",
  "status": "CREATED",
  "created": "2022-03-02T13:38:22.784359Z",
  "workspace": "88431559-20ea-4d43-98a6-7a1cb38160e3"
}

GET/v2/request/__ID__/status

Get Request Status

Quickstart

Get the current status of an asynchronous request.

Returns

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

Name
status
Type
string
Description
Current status of the request (CREATED, PROCESSING, DONE).

Request

GET

/v2/request/__ID__/status

curl https://api.ximilar.com/account/v2/request/__REQUEST_ID__/status \
  -H "Content-Type: application/json" \
  -H "Authorization: Token __API_TOKEN__"

Response

{
  "status": "DONE"
}

GET/v2/request/__ID__

Get Request Details

Quickstart

Get the full details of an asynchronous request, including results if the request is completed.

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
Unique identifier of the request.
Name
status
Type
string
Description
Current status of the request.
Name
request
Type
object
Description
Original request data.
Name
response
Type
object
Description
Response data (only present if status is DONE).
Name
created
Type
string
Description
Timestamp when the request was created (ISO 8601 format).
Name
modified
Type
string
Description
Timestamp when the request was last modified (ISO 8601 format).
Name
workspace
Type
string
Description
Workspace identifier.

Request

GET

/v2/request/__ID__

curl https://api.ximilar.com/account/v2/request/__REQUEST_ID__ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token __API_TOKEN__"

Response

{
  "id": "2e9b43f2-61be-4aaa-8a6a-a74fc0f80b57",
  "created": "2022-03-02T13:38:22.784359Z",
  "modified": "2022-03-02T13:38:22.784359Z",
  "request": {
    "type": "upscaler",
    "records": [
      {
        "_id": "2e9b43f2-61be-4aaa-8a6a-a74fc0f80b57",
        "_url": "https://images.ximilar.com/examples/fashion_products/01_1149810256_SI_00.jpeg"
      }
    ],
    "endpoint": "upscale_2x"
  },
  "response": {
    "records": [
      {
        "_id": "2e9b43f2-61be-4aaa-8a6a-a74fc0f80b57",
        "_url": "https://images.ximilar.com/examples/fashion_products/01_1149810256_SI_00.jpeg",
        "_width": 800,
        "_height": 1200,
        "_status": {
          "code": 200,
          "text": "OK",
          "request_id": "b61e7879-8038-445b-a617-de4be5b2e447"
        },
        "_upscaled_width": 1600,
        "_upscaled_height": 2400,
        "_upscaled_image_url": "https://s3-eu-west-1.amazonaws.com/ximilar-tmp-images/upscale/dce17b2c-e9ad-4870-9fa8-470ba633ea0a.jpg"
      }
    ]
  },
  "type": "upscaler",
  "status": "DONE",
  "workspace": "88431559-20ea-4d43-98a6-7a1cb38160e3"
}

GET/v2/request/

List Requests

Quickstart

Get a paginated list of all asynchronous requests submitted by the user. This will return a pagindated results with all states (CREATED, PROCESSING, DONE) of requests. The asynchronous requests are automatically deleted after 7 days.

Optional query parameters

Name
type
Type
string
Description
Filter requests by type (upscaler, flows, collectibles-recognition, card-grader).
Name
status
Type
string
Description
Filter requests by status (CREATED, PROCESSING, DONE).

Returns

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

Name
count
Type
integer
Description
Total number of requests.
Name
next
Type
string
Description
URL for the next page of results (null if no more pages).
Name
previous
Type
string
Description
URL for the previous page of results (null if first page).
Name
results
Type
array
Description
An array of request objects.

Request

GET

/v2/request/

curl "https://api.ximilar.com/account/v2/request/?status=DONE&type=upscaler" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token __API_TOKEN__"

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "2e9b43f2-61be-4aaa-8a6a-a74fc0f80b57",
      "status": "DONE",
      "type": "upscaler",
      "created": "2022-03-02T13:38:22.784359Z",
      "workspace": "88431559-20ea-4d43-98a6-7a1cb38160e3"
    },
    {
      "id": "1abea671-400c-4fa3-9f30-be29a5cdea32",
      "status": "DONE",
      "type": "upscaler",
      "created": "2022-03-02T13:03:59.176871Z",
      "workspace": "88431559-20ea-4d43-98a6-7a1cb38160e3"
    }
  ]
}

Webhook Notifications

When a request is completed and a if a webhook endpoint was specified, the system sends a POST request to that endpoint with the following JSON structure:

{
  "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 include custom headers in the webhook configuration; these headers will be sent with the webhook notification:

{
  "webhook": {
    "endpoint": "__YOUR_POST_URL__",
    "headers": {
      "optional_field": "optional_value"
    }
  }
}