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, choose the API client you want to use. In addition to good ol' cURL for HTTP requests, Ximilar also provides a Python client.

Below is how to check/install each client:

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

Authentication

All requests to the Ximilar API must include your API token in the request headers. This applies to all HTTP methods: GET, POST, PUT, and DELETE.

Required headers:

• Authorization: Include your token prefixed by "Token "
• Content-Type: Set to application/json

Example:

Authorization: Token 1af538baa90-----XXX-----baf83ff24
Content-Type: application/json```

Making Your First API Request

Once you've selected your client, you're ready to make your first call to the Ximilar API. Here's how to send a GET request to the account endpoint /v2/details to retrieve your account info.

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 like this:

{
    "id": "21073c04-5308-47fe-a403-ce5385d859de",
    "email": "test@ximilar.com",
    "first_name": "FIRST",
    "last_name": "NAME",
    "phone": null,
    "organization": "COMPANY",
    "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 follows the REST architecture, meaning you can interact with it using standard HTTP requests. Most methods require a request body in JSON format, and all responses are returned as JSON.

Image Data

API methods that work with images accept them in following formats:

• _url – a public URL to download the image
• _base64 – the image file encoded in Base64

Image data is typically passed in JSON fields like:

• records – used in tagging and OCR services
• query_record – used in single-image similarity search
• query_records – used in multi-image similarity search Each of these fields 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

To send local images, convert them to Base64. You can:

• Directly encode the compressed image file (e.g., PNG, JPEG, WebP)
• Send uncompressed pixel data. If using pixel arrays (e.g., ndarray), make sure to convert the image to BGR channel order before encoding it to Base64.

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 an image via URL, the image must be publicly accessible on the internet. It must be a direct link to the image file (e.g. ending with .jpg, .png, .webp).

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

Supported Image Formats

Our API accepts following image formats (in fields of _base64 or _url):

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

Formats with limited support:

GIF (only the frame will be loaded)

Following formats are not supported:

AVIF, JP2, PSD, SVG, HEIF, PDF

API Calls and Credits

Ximilar’s pricing is based on API method calls (requests), with each request consuming a certain number of credits depending on the method’s complexity. For instance, an identification of a single trading card via the Collectibles Recognition API costs 10 credits.

Key points about credits and billing:

• Free plan users receive a monthly supply of credits for testing
• Paid plans offer customizable monthly credit supplies based on your needs (expected usage)
• You can track your credit usage on the Ximilar App Dashboard and Statistics page

Batch Processing

Some endpoints, such as the Collectibles Recognition services, support batch processing. This allows you to send up to 10 images (records) in a single request via the records field.

• The response preserves the order of the submitted records.
• Each image (record) is billed individually depending on the service and operation – see Pricing.

For example, if you send a request with 3 records/images, each one will be processed and charged individually.

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

What's Next?

Great! You've successfully sent your first API request, understood the common request/response format, and learned how to encode and send images for analysis.

Here are a few helpful links as you continue exploring the Ximilar API:

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