Custom Similarity

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.

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.

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

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

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

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

Type endpoint - /v2/type/

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

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

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

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

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

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

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

Group 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.

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

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/

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

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'

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__"]}'

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__"]}'

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__"]}'

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__"]}'

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

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}'

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

Training image endpoint let you upload training images.

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

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 -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" }]}'