Asynchronous Requests

Quickstart SDKs Test in APP

This page describes how to use Asynchronous Requests for processing large numbers of images. With this service you can submit multiple requests at once and process them in the background. The API provides endpoints for submitting requests, checking their status, and retrieving results.

If you need to process large number of requests per day or month (millions of requests) and don't need to get the results immediately, then asynchronous requests with webhooks are the perfect solution for you.

Supported Services

The following services support asynchronous processing:

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/          (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

Submit a new asynchronous request for processing. Each request is identified by a unique id (UUID). The request will be stored in our database with the state CREATED. Once a worker takes the request for analysis, its state changes to PROCESSING. Completed requests have the state DONE.

Required attributes

Name
type
Type
string
Description
Type of the request (upscaler, flows, collectibles-recognition, card-grader)
Name
records
Type
array
Description
A batch of json records (max 10), one record is representation of an image and it's defined by _url or _base64.

Optional attributes

Name
webhook
Type
object
Description
Optional webhook configuration for notifications when request status changes to DONE. Contains endpoint (URL) and optional headers.
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. 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 (CREATED, PROCESSING, DONE)
Name
type
Type
string
Description
Type of the request
Name
created
Type
string
Description
Timestamp when the request was created
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. Body of the response 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
Name
modified
Type
string
Description
Timestamp when the request was last modified
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.

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. Body of the response 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
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, if a webhook endpoint was specified, we will send 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 specify custom headers that will be sent with the webhook notification by including them in the webhook configuration:

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