Quickstart

This guide will get you all set up and ready to use the Ximilar API. We'll cover how to get started with API and how to make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API.

Choose your client

Before making your first API request, you need to pick which API client you will use. In addition to good ol' cURL HTTP requests, Ximilar offers client for Python. In the following example, you can see how to install each client.

# cURL is most likely already installed on your machine
curl --version

Authentication

User authentication and authorization is done through a API key (token) in the header of each HTTP request. Be aware that your Authorization header should include "Token " string prefix with your token, so "Token _YOUR_API_TOKEN". This authorization token is required in all HTTP methods as GET, POST, PUT, DELETE. When making request to our API, do not forget to include also Content-Type: application/json header. Here is a sample of authorization token in the header:

Authorization: Token 1af538baa90-----XXX-----baf83ff24

Making your first API request

After picking your preferred client, you are ready to make your first call to the Ximilar API. Below, you can see how to send a GET request to the account endpoint to get information about your account.

curl --location 'https://api.ximilar.com/account/v2/details/' \
--header 'Authorization: Token __YOUR_API_KEY__' \
--header 'Content-Type: application/json'

The output is JSON based and looks very similar to this:

{
    "id": "21073c04-5308-47fe-a403-ce5385d859de",
    "email": "test@ximilar.com",
    "first_name": "FIRST",
    "last_name": "NAME",
    "phone": null,
    "organization": "Ximilar",
    "verified": true,
    "credits_counter": 103378706,
    "credits_limit": 2147483647,
    "default_workspace": "58421549-21ea-3d43-94a6-6a1cb38160e3",
    ...
}

Congratulations you have made your first API request!

JSON Requests

Our API is based on REST API. This means that you can query our API with HTTP requests. Most of the API methods require a body in JSON format and all of the methods return data in JSON format.

All API methods that work with image data can contain either a URL (_url) to download the image from or a the actual binary image data encoded as Base64 (_base64). Typically, the images are passed within JSON field records (usually tagging services) or query_record (usually similarity search services) or query_records (usually similarity search services) which contains a JSON array with the image records.

{
  "records": [
    {
      "_id": "YOUR_ID",
      "_url": "https://example.com/my_image.jpg",
      "other_record_field": "value"
    }
  ],
  "other_request_field": "value"
}

Loading and sending images

If you want to send a locally stored images then you will need to load and convert image to base64. Base64 data format means that you can either directly encode the compressed image file (PNG, JPEG, WebP) from your drive or you can send the "uncompressed" pixel data. If you want to send uncompressed data - ndarray, convert image first to BGR order of channels and then to base64 format.

import base64, requests

with open(__IMAGE_PATH__, "rb") as image_file:
    encoded_string = base64.b64encode(image_file.read()).decode('utf-8')

data = {"records": [{"_base64": encoded_string}]}
response = requests.post(endpoint, headers=headers, data=json.dumps(data))

If you want to send image via url then the image must be publicly accessible on the internet. The image cannot be link to google drive image or to any html website, it must be a direct link to the image.

response = requests.post(endpoint, headers=headers,
  data=json.dumps({"records": [{"_url": "__IMG_URL__"}]})
)

Supported Image Formats

Right now you can send images to the api (in fields of _base64 or _url) with these supported formats:

JPG, JPEG, PNG, WEBP, HEIC, BMP, TIFF, JFIF

Formats with limited support:

GIF (we load only first frame)

We are not supporting:

GIF, AVIF, JP2, PSD, SVG, HEIF, PDF

API Calls and Credits

Ximilar billing is based on the number of API method calls (requests made to the Ximilar API). To differentiate between different complexity of the methods, every api call corresponds to a certain number of credits. For example identification of one card via Collectibles Recognition API cost 10 credits. New Ximilar users have some free monthly credits to be used for testing. Then, there are several pricing plans with different amount of available credits and other limits. You can see the number of credits you have used in current month in the Ximilar app dashboard.

In general, each API call that sends or uploads an image for AI analysis to Ximilar API endpoint costs some credits. All other methods are for free.

Batch processing

Some of our endpoints support batch processing, for example Collectibles Recognition services for cards and comics identification. That means you can send up to 10 images (records) in one request. The order of the records in response is preserved. If we have for example following request with 3 records / images, then each record is billed for analysis separately:

data = [
  {"_id": "1", "_url": "_IMG_URL_1"},
  {"_id": "2", "_base64": "_BASE64_DATA_"},
  {"_id": "3", "_url": "_IMG_URL_2"}
]

What's next?

Great, you send your first API request and understand the common format of request and response, you also know how to encode and send your images for analysis. Here are a few links that might be handy as you venture further into the Ximilar API:

• Read about Computer Vision Platform API
• Test Collectibles Recognition API
• Explore Visual Search Services