Asynchronous Requests

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.

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

Was this page helpful?