Asynchronous Requests
For the following services we are allowing to call requests in asynchronous way:
Why asynchronous requests? You can call/create much more requests at once in asynchronous way than with synchronous way. You just need to store the id of the requests and then later query them and check the results. Some of the synchronous endpoints can take a lot of time for completed processing (upscaler). That is why the asynchronous requests are better.
Each createad request is identified by id (UUID). When submitting request you will need to specify type of requests. After submitting the request via REST API (POST), the request is stored in our database with the state CREATED. Once the specific worker take the request for analysis the request changed it's state to PROCESSING. Completed request has state DONE. Processing of request can take several seconds to minutes (depends on number of requests in queue). Please store id of the submitted request for getting results.
WEBHOOK
You can specify your own endpoint which we will notife after the request changes its status to DONE. The webhook specification is optional.
Querying Requests
For getting list of all asynchronous requests (pagindated results) submitted by user, you can call:
curl --request GET \
--url https://api.ximilar.com/account/v2/request/ \
--header 'Authorization: Token __AUTH_TOKEN__' \
--header 'Content-Type: application/json'
from ximilar.client.asyncr import AsyncRClient
client = AsyncRClient(__API_TOKEN__)
requests, next_page, status = client.get_requests(page_url=None)
CLICK TO SHOW JSON RESULT
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": "2e9b43f2-61be-4aaa-8a6a-a74fc0f80b57",
"status": "PROCESSING",
"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"
}
]
}
For getting list of all asynchronous request submitted by user, with filtering on type and status:
curl --request GET \
--url 'https://api.ximilar.com/account/v2/request/?status=DONE&type=UPSCALER' \
--header 'Authorization: Token __AUTH_TOKEN__' \
--header 'Content-Type: application/json'
from ximilar.client.asyncr import AsyncRClient
client = AsyncRClient(__API_TOKEN__)
requests, next_page, status = client.get_requests(page_url=None, type="upscaler", status="DONE")
CLICK TO SHOW JSON RESULT
{
"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"
}
]
}
Get status of request with specific ID:
curl --request GET \
--url https://api.ximilar.com/account/v2/request/__REQUEST_ID__/status \
--header 'Authorization: Token __AUTH_TOKEN__' \
--header 'Content-Type: application/json'
from ximilar.client.asyncr import AsyncRClient
client = AsyncRClient(__API_TOKEN__)
request, _ = client.get_request(__ID__)
print(request.check_status())
CLICK TO SHOW JSON RESULT
{
"status": "DONE"
}
Get result of request (result in response field is present only if the request is in status DONE):
curl --request GET \
--url https://api.ximilar.com/account/v2/request/__REQUEST_ID__ \
--header 'Authorization: Token __AUTH_TOKEN__' \
--header 'Content-Type: application/json'
from ximilar.client.asyncr import AsyncRClient
client = AsyncRClient(__API_TOKEN__)
request, _ = client.get_request(__ID__)
CLICK TO SHOW JSON RESULT
{
"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"
}
Upscaler Requests
The required fields for request are type, endpoint and records. Optionally you can specify mode. The endpoint field must one of [upscale_2x,upscale_4x,upscale_8x]. Be aware that the result field _upscaled_image_url has limited expiration of one day. If you want to use GAN (Generative) model please include field model_type with value gan in request. If you want to use classic model then omit the field. Only one record/photo is possible inside records when submitting request. You can specify webhook with endpoint to get notification of completed request. You can also specify output image_format and image_quality, for more info see Upscaler page.
For creating the asynchronous request you will need to call the API endpoint in following way:
curl --request POST \
--url https://api.ximilar.com/account/v2/request \
--header 'Authorization: Token __AUTH_TOKEN__' \
--header 'Content-Type: application/json' \
--data '{
"type": "upscaler",
"endpoint": "upscale_2x",
"mode": "high_fidelity",
"model_type": "gan",
"image_format": "webp",
"records": [
{
"_url": "__URL_PATH__"
}
],
"webhook": {
"endpoint": "__YOUR_POST_URL__",
"headers": {"optional_field": "optional_value"}
}
}'
from ximilar.client.asyncr import AsyncRClient
client = AsyncRClient(__API_TOKEN__)
request, _ = client.submit({"records":[{"_url":"__URL_PATH__"}]}, "upscaler", endpoint="upscale_2x")
time.sleep(20) # lets wait
request.update()
print(request.response)
CLICK TO SHOW JSON RESULT
{
"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"
}
When the request is finished, response.status is changed to DONE. Response from getting result looks similar to this, the filled response contains upscaled image (This data are also sent to specified webhook, see next section):
CLICK TO SHOW JSON RESULT
{
"id": "622b1db9-754b-4c60-9f41-34b9ea3cce34",
"created": "2023-04-19T12:22:40.209752Z",
"modified": "2023-04-19T12:22:44.204392Z",
"request": {
"type": "upscaler",
"records": [
{
"_id": "abc",
"_url": "https://images.ximilar.com/examples/fail/mini.png"
}
],
"webhook": {
"endpoint": "__YOUR_WEBHOOK__"
},
"endpoint": "upscale_2x",
"model_type": "gan"
},
"response": {
"records": [
{
"_id": "abc",
"_url": "https://images.ximilar.com/examples/fail/mini.png",
"_width": 212,
"_height": 174,
"_status": {
"code": 200,
"text": "OK",
"request_id": "622b1db9-754b-4c60-9f41-34b9ea3cce34"
},
"_upscaled_width": 424,
"_upscaled_height": 348,
"_upscaled_image_url": "__URL_PATH_TO_IMAGE_RESULT__"
}
]
},
"type": "upscaler",
"status": "DONE",
"workspace": "88431559-20ea-4d43-98a6-7a1cb38160e3"
}
Webhook in request
We will send the POST JSON request to the specified endpoint (you can specify it in the webhook field, see upscaler example request above). In this way you will know when to query the results. Your specified endpoint should accept json data that are 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"}
}
}
Flows Requests
The required fields for request is type, flow identification and records.
For creating the asynchronous request you will need to call the API endpoint in following way:
curl --request POST \
--url https://api.ximilar.com/account/v2/request \
--header 'Authorization: Token __AUTH_TOKEN__' \
--header 'Content-Type: application/json' \
--data '{
"type": "flows",
"flow": "__ID__",
"records": [
{
"_url": "__URL_PATH__"
}
],
"webhook": {
"endpoint": "__YOUR_POST_URL__",
"headers": {"optional_field": "optional_value"}
}
}'
from ximilar.client.asyncr import AsyncRClient
import time
client = AsyncRClient(__API_TOKEN__)
request, _ = client.submit({"records":[{"_url":"__URL_PATH__"}]}, "flows", flow="__FLOW_ID__")
time.sleep(10)
request.update()
print(request.response)
CLICK TO SHOW JSON RESULT
{
"id": "2e9b43f2-61be-4aaa-8a6a-a74fc0f80b57",
"request": {
"flow": "__ID__",
"records": [
{
"_url": "https://images.ximilar.com/examples/fashion_products/01_1149810256_SI_00.jpeg"
}
]
},
"type": "flows",
"status": "CREATED",
"created": "2022-03-02T13:38:22.784359Z",
"workspace": "88431559-20ea-4d43-98a6-7a1cb38160e3"
}
Collectibles Requests
The required fields for request is type, endpoint (with sport_id, tcg_id, comics_id) and records.
For creating the asynchronous request you will need to call the API endpoint in following way:
curl --request POST \
--url https://api.ximilar.com/account/v2/request \
--header 'Authorization: Token __AUTH_TOKEN__' \
--header 'Content-Type: application/json' \
--data '{
"type": "collectibles-recognition",
"endpoint": "sport_id",
"records": [
{
"_url": "__URL_PATH__"
}
],
"webhook": {
"endpoint": "__YOUR_POST_URL__",
"headers": {"optional_field": "optional_value"}
}
}'
CLICK TO SHOW JSON RESULT
{
"id": "7287a9e3-e7c3-4000-a682-85d5080eb7fa",
"request": {
"records": [
{
"_url": "__URL_PATH__"
}
],
"type": "collectibles-recognition",
"endpoint": "sport_id"
},
"type": "collectibles-recognition",
"status": "CREATED",
"created": "2024-08-26T15:42:17.021211Z",
"workspace": "88231539-20ea-4dd3-9da6-7a1cb24160e3"
}
Card Grading Requests
The required fields for request is type, endpoint (with grade, condition, condition) and records.
For creating the asynchronous request you will need to call the API endpoint in following way:
curl --request POST \
--url https://api.ximilar.com/account/v2/request \
--header 'Authorization: Token __AUTH_TOKEN__' \
--header 'Content-Type: application/json' \
--data '{
"type": "card-grader",
"endpoint": "grade",
"records": [
{
"_url": "__URL_PATH__"
}
],
"webhook": {
"endpoint": "__YOUR_POST_URL__",
"headers": {"optional_field": "optional_value"}
}
}'
CLICK TO SHOW JSON RESULT
{
"id": "7287a9e3-e7c3-4000-a682-85d5080eb7fa",
"request": {
"records": [
{
"_url": "__URL_PATH__"
}
],
"type": "card-grader",
"endpoint": "grade"
},
"type": "card-grader",
"status": "CREATED",
"created": "2024-08-26T15:42:17.021211Z",
"workspace": "88231539-20ea-4dd3-9da6-7a1cb24160e3"
}