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.
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)
Submit Request
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 optionalheaders
. Used to notify your server (by calling specific endpoint) when the request status changes toDONE
.
- 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
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 Request Status
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
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 Request Details
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
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"
}
List Requests
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
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"
}
}
}