Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

CraftAR Python Library


The Craftar Service for Image Recognition is a service that allows you to build a wide range of Image Recognition applications and services.

With Craftar, you can create amazing apps that provide digital content for real-life objects like printed media, packaging among others. You can use our online web panel or APIs, to upload images to be recognized and set content to display upon recognition in your CraftAR-powered app.

This client library provides access to CraftAR APIs:

The library also provides tools for performing batch operations:


If you already have Python and pip on your system you can install the library simply by running:

pip install craftar

In case you first need to install Python or pip, please follow specific instructions for your operating system.


On Windows we recommend using the library within Cygwin, which provides a Linux look and feel environment:

  1. Download Cywin installer from the official page.
  2. In the installer wizard, select all python packages, and libmpfr-devel (under libs category).
  3. Open the Cygwin shell and execute the following commands:
easy_install pip
pip install craftar

Mac OS X

Python comes pre-installed on Mac OS X, so typically you only need to add pip:

easy_install pip
pip install craftar


Quick Start

Follow these steps to create a collection with one item and perform an image recognition request against that collection. A collection is a set of items representing entities that you want to recognize. Examples of items are logos, physical objects, or a drawings, among others. You can do it directly from your python interpreter.

  1. Get your management api_key. This is needed to authenticate your requests to the Management API.

    import craftar
    # use your own api_key!
    api_key = "35d5919334816e239bba08637e6aa457e8ca92c8"
  2. Create a new collection.

    name = "My cool colection" # use your own collection name
    collection = craftar.create_collection(api_key, name)
  3. Keep the token of that collection, you will need it later for the recognition:

    token_list = craftar.get_token_list(api_key, limit=1, offset=0,
    token = token_list[0]["token"] # first token on the list
  4. Create an empty item in your collection:

    name = "My cool item" # use your own item name
    url = "" # and your own url
    custom = "This is my custom data" # and your own custom data
    item = craftar.create_item(api_key, collection["uuid"], name, url, custom)
  5. Upload an image representing your item.

  • Every item can be represented by one or more reference images. This is useful for items that have different faces, e.g. cereal boxes.

  • Before performing a successful recognition, the corresponding reference image needs to be fully indexed by the server. Normally it takes less than one second after uploading.

    filename = "reference.jpg" # use your own image
    image = craftar.create_image(api_key, item["uuid"], filename)
  1. Now you are ready to perform the image recognition request against your collection.
  • You will also need the token you saved in step 3 and the image to be recognized.

    # remember that you set _token_ in step 3
    filename = "query.jpg" # use your own query image
    result_list =, filename)
  1. Done! You can print the result:

    print result_list
    • Each returned reference image has an associated score, indicating its relevancy to the query image.


The scripts under /bin allow batch operations against the APIs:

  • craftar_search sends one or several Image Recognition requests against the CraftAR Service. Specifically, it performs visual scans against the collection (specified by the token) using every image in the provided directory.
  • craftar_upload uploads a set of reference images to the CraftAR Service. It iterates over the contents of the specified directory and uploads all the images (and, if provided, also their associated metadata) to a new or an existing collection.


In order to see reference implementations demonstrating the most common operations that can be performed with our APIs check the scripts under the examples folder:

  • example_list_paginated_items: Lists all your items. If required, the listed items can be limited to a specific collection.
  • example_management: Demonstrates listing, creation, updating and deletion of every type of object (i.e. collection, item, image, token).

For the reference implementation of the recognition operation see the script craftar_search script under /bin.

Reporting Issues

If you have suggestions, bugs or other issues specific to this library, file them here or contact us at


CraftAR Python Library




No packages published