Custom Similarity

PRICING

Ximilar Custom Similarity service provides an API to train similarity models which are used for extracting visual embeddings/descriptor/vectors. The model extract embedding for every image which are then inserted to your custom similarity collection. This service allows you to implement state-of-the-art artificial intelligence into your project. It’s easy, quick and highly scalable.

BETA PRODUCT

This product is in development/beta. If you are interested in this service please write us at sales@ximilar.com.

Python Library

If you are using Python programming language in your project you can query our API with our library. Our library is available on gitlab and through the pypi.

Why this service?

We provide Photo and Product similarity service with focus on generic and fashion photos. Overtime some of our customers would like to train their own similarity models on their images. This service allows you to create your definition of similarity. You can train model that will be based on colors or purely on shape or other features that you define through the collection of your Similarity Group...

Terminology

The task is where you start. Each task has a set of Similarity Type. For training your task and getting using trained model you will need to upload images and add them to Similarity Group.

Model is the trained machine learning model behind your task. Its a neural network trained on your specific images and groups. Model is private only to its owner. Each retraining increases the version of the model by one and you can select a model version that is deployed and connected to specific Collection.

Similarity Type is a feature that defines your Similarity Groups. Every Similarity Group is defined by Similarity Type. One Similarity Group can contains several images or other Similarity Group.

Simple example

For example if you have fashion products and each product contains several photos you can create Similarity Type with name "Individual Product". Then every photo of individual fashion product can be in one Similarity Group with type "Individual Product". You can create a thousands of these groups for your products. You can mark individual images as product photo (if they are on present ) or real photo.

You can also create another Similarity Type with name "Similar Products" and create groups which will connect "Individual Product" groups.

You can then connect "Similar Products" and "Individual Product" to your new task and train your similarity model.

If you trained your model and you would like to search in your data with this model, then you will need to create new Collection and connect model to this collection. Then you need to insert all the records/images to the collection by calling api endpoint for insert. See next section for collection management.

Collection endpoints

If you already have your collection created and you know ID of the collection then you can insert, search or delete records/images. All the endpoints work in same way as Ximilar Search API. The only difference is that that the base url is:

https://api.ximilar.com/similarity/custom/v2/[METHOD]

Most of the time you will need METHOD for insert (to fill up collection) and search (for finding visually similar). You will need to specify --colection-id in header of request when working with them.

Task endpoint - /v2/task/

Task endpoints let you manage tasks in your account. You can list all the tasks, create, delete, and modify created tasks. Until the first task training is successfully finished the production version of the task is -1 and the task cannot be used for classification.

List tasks (returns paginated result):

Curl

curl -v -XGET -H 'Authorization: Token __API_TOKEN__' https://api.ximilar.com/similarity/training/v2/task

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
tasks, _ = client.get_all_tasks()

Create Task:

Curl

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__' -F 'name=__YOUR_NAME__' https://api.ximilar.com/similarity/training/v2/task

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
task, _ = client.create_task("__NAME__", "__DESCRIPTION__")

Get Task:

Curl

curl -v -XGET -H 'Authorization: Token __API_TOKEN__' -F 'name=__YOUR_NAME__' https://api.ximilar.com/similarity/training/v2/task/__ID__

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
task, _ = client.get_task("__TASK_ID__")

Delete task:

Curl

curl -v -XDELETE -H 'Authorization: Token __API_TOKEN__' https://api.ximilar.com/similarity/training/v2/task/__TASK_ID__/

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
task, _ = client.get_task("__TASK_ID__")
task.remove()

Type endpoint - /v2/type/

Type endpoints let you manage Simlarity Type. Each task requires at least one type for training.

List all your types (returns paginated result):

Curl

curl -v -XGET -H 'Authorization: Token __API_TOKEN__' https://api.ximilar.com/similarity/training/v2/type

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
types, _ = client.get_all_types()

Get Type:

Curl

curl -v -XGET -H 'Authorization: Token __API_TOKEN__' -F 'name=__YOUR_NAME__' https://api.ximilar.com/similarity/training/v2/type/__ID__

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
type1, _ = client.get_type("__TYPE_ID__")

Create Type:

Curl

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__' -F 'name=__YOUR_NAME__' https://api.ximilar.com/similarity/training/v2/type

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
type1, _ = client.create_type("__NAME__", "__DESCRIPTION__")

Remove a type from your task:

Curl

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__' -F 'type_id=__TYPE_ID__' https://api.ximilar.com/similarity/training/v2/task/__TASK_ID__/remove-type

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
task, _ = client.get_task("__TASK_ID__")
task.remove_type("__TYPE_ID__")

Add a type from your task:

Curl

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__' -F 'type_id=__TYPE_ID__' https://api.ximilar.com/similarity/training/v2/task/__TASK_ID__/add-type

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
task, _ = client.get_task("__TASK_ID__")
task.add_type("__TYPE_ID__")

Delete type (WARNING this will delete also all the groups of this type):

Curl

curl -v -XDELETE -H 'Authorization: Token __API_TOKEN__' https://api.ximilar.com/similarity/training/v2/type/__TYPE_ID__/

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
type1, _ = client.get_type("__TYPE_ID__")
type1.remove()

Type endpoint - /v2/group/

Type endpoints let you manage Simlarity Type in your tasks. Each task requires at least one type for training. A group can contain only images or only groups.

List all your groups (returns paginated result):

Curl

curl -v -XGET -H 'Authorization: Token __API_TOKEN__' https://api.ximilar.com/similarity/training/v2/group

Crate a group with a type:

Curl

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__' -F 'name=_SOME_GROUP_NAME_' -F 'type=_TYPE_ID_' https://api.ximilar.com/similarity/training/v2/group/

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
group, _ = client.create_group("__NAME__", "__DESCRIPTION__", "__TYPE_ID__")

Get group:

Curl

curl -v -XGET -H 'Authorization: Token __API_TOKEN__' https://api.ximilar.com/similarity/training/v2/group/__GROUP_ID__

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
group, _ = client.get_group("__GROUP_ID__")

Search groups with name:

Curl

curl --request GET \
  --url 'https://api.ximilar.com/similarity/training/v2/group/?search=_SOME_GROUP_NAME_' \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'content-type: application/json'

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
groups, _ = client.get_all_groups_by_name("__NAME__")

Add an image to your group:

Curl

curl --request POST \
  --url https://api.ximilar.com/similarity/training/v2/group/__GROUP_ID__/add-images \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'content-type: application/json' \
  --data '{"images":["__IMAGE_ID__"]}'

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
group, _ = client.get_group("__GROUP_ID__")
group.add_images(["__IMAGE_ID_1__", "__IMAGE_ID_2__"])

Remove an image from your group:

Curl

curl --request POST \
  --url https://api.ximilar.com/similarity/training/v2/group/__GROUP_ID__/remove-images \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'content-type: application/json' \
  --data '{"images":["__IMAGE_ID__"]}'```

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
group, _ = client.get_group("__GROUP_ID__")
group.remove_images(["__IMAGE_ID_1__", "__IMAGE_ID_2__"])

Add a group to group:

Curl

curl --request POST \
  --url https://api.ximilar.com/similarity/training/v2/group/__GROUP_ID__/add-groups \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'content-type: application/json' \
  --data '{"groups":["__GROUP_ID__"]}'

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
group, _ = client.get_group("__GROUP_ID__")
group.add_groups(["__GROUP_ID_1__", "__GROUP_ID_2__"])

Remove a group from group:

Curl

curl --request POST \
  --url https://api.ximilar.com/similarity/training/v2/group/__GROUP_ID__/remove-groups \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'content-type: application/json' \
  --data '{"groups":["__GROUP_ID__"]}'

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
group, _ = client.get_group("__GROUP_ID__")
group.remove_groups(["__GROUP_ID_1__", "__GROUP_ID_2__"])

Delete group:

Curl

curl -v -XDELETE -H 'Authorization: Token __API_TOKEN__' https://api.ximilar.com/similarity/training/v2/group/__GROUP_ID__/

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
group, _ = client.get_group("__GROUP_ID__")
group.remove()

Change group to test for independent evaluation dataset (all the connected should be also test):

Curl

curl --request POST \
  --url https://api.ximilar.com/similarity/training/v2/group/update \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'content-type: application/json' \
  --data '{"groups": ["__GROUP_ID__"], "mark-test": true}'

Python

from ximilar.client.similarity import CustomSimilarityClient
client = CustomSimilarityClient("__API__TOKEN__")
group, _ = client.get_group("__GROUP_ID__")
group.set_test(True) # set to test
#group.set_test(False) # unset it back to training

Training image endpoint - /recognition/v2/training-image/

Training image endpoint let you upload training images.

Upload training image:

Curl

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__' -F 'img_path=@__FILE__;type=image/jpeg' https://api.ximilar.com/recognition/v2/training-image/

Python

from ximilar.client import RecognitionClient

client = RecognitionClient(token="__API_TOKEN__")

images, status = client.upload_images([{'_url': '__URL_PATH_TO_IMAGE__', 'labels': [], "meta_data": {"field": "key"}},
                                       {'_file': '__LOCAL_FILE_PATH__', 'labels': []},
                                       {'_base64': '__BASE64_DATA__', 'labels': []}])

# Upload image without resizing it (for example Custom Object Detection requires high resolution images):
images, status = client.upload_images([{'_url': '__URL_PATH_TO_IMAGE__', "noresize": True}])

Delete image:

Curl

curl -v -XDELETE -H 'Authorization: Token __API_TOKEN__' https://api.ximilar.com/recognition/v2/training-image/__IMAGE_ID__/

Descriptor endpoint - /v2/descriptor

Most of the time you don't need to use this endpoint at all. Getting visual descriptors/embeddings for the images.

Curl

curl -H "Content-Type: application/json" -H "authorization: Token __API_TOKEN__" https://api.ximilar.com/similarity/training/v2/descriptor -d '{"collection": "__COLLECTION_ID__", "records": [ {"_url": "https://bit.ly/2IymQJv" }]}'