Platform – Custom Similarity

Basics Quickstart Ximilar Platform Video Tutorials

This product is available on a Professional plan. Please contact us before purchasing the plan and using the service at tech@ximilar.com for more information.

The Custom Similarity service provides an API for training similarity models that extract visual embeddings (also called descriptors or vectors) from images. Each image is processed by the model to generate an embedding, which can then be added to your custom similarity collection.

This service enables you to integrate state-of-the-art artificial intelligence into your project. It's easy to use, fast, and highly scalable.

All Endpoints

There are several useful API endpoints that you can use:

https://api.ximilar.com/similarity/training/v2/task
https://api.ximilar.com/similarity/training/v2/task/__TASK_ID__
https://api.ximilar.com/similarity/training/v2/task/__TASK_ID__/add-type
https://api.ximilar.com/similarity/training/v2/task/__TASK_ID__/remove-type

POST/v2/descriptor

Extract Descriptor

Extracts visual descriptors (embeddings) from images. This endpoint is used to get the vector representation of each image, which can be used for similarity search. You can specify the model for extraction using either a collection ID or a task ID.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
records
Type
array
Description
An array of image records to process. Each record must contain either _url or _base64 field.
Name
collection
Type
string
Description
UUID of the collection to use for extraction. Either this or task_id must be provided.
Name
task_id
Type
string
Description
UUID of the task to use for extraction. Either this or collection must be provided.
Name
version
Type
integer
Description
Version of the model to use. Required when using task_id.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. The response body is a JSON object containing the extracted descriptors for each image.

Request

POST

/v2/descriptor

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

Response

{
  "records": [
    {
      "_id": "__RECORD_ID__",
      "_url": "__IMG_URL__",
      "_width": WIDTH,
      "_height": HEIGHT,
      "_descriptor": [
        -0.0116, -0.0446, -0.0821, 0.0178, -0.0081,
        // ... descriptor values ...
        -0.0725
      ],
      "_status": {
        "code": 200,
        "text": "OK",
        "request_id": "__REQUEST_ID__"
      }
    }
  ],
  "version": 8,
  "task_id": "__TASK_ID__",
  "status": {
    "code": 200,
    "text": "OK",
  },
  "statistics": {
    "processing time": 0.5454964637756348
  }
}

POST/v2/task/

Create Task

Create a new task for custom similarity training.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
name
Type
string
Description
Name of the task.

Optional attributes

Name
description
Type
string
Description
Description of the task.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. The body of the response is a JSON object containing the created task details.

Request

POST

/v2/task/

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

GET/v2/task/

List Tasks

List all tasks in your account. Returns paginated results.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. The response body is a JSON object containing paginated list of tasks.

Request

GET

/v2/task/

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

POST/v2/type/

Create Type

Create a new similarity type for your tasks. Each task requires at least one type for training. Similarity type defines how the images are grouped together for training a similarity model.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
name
Type
string
Description
Name of the similarity type.

Optional attributes

Name
description
Type
string
Description
Description of the similarity type.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. The body of the response is a JSON object containing the created type details.

Request

POST

/v2/type/

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

POST/v2/group/

Create Group

Create a new similarity group with a specific type. A group is a basic entity for training a similarity model. It can only contain images, objects, or other groups. The group is important for training a similarity model, as it defines (groups) the images that are considered similar to each other.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
name
Type
string
Description
Name of the group.
Name
type
Type
string
Description
UUID of the similarity type.

Optional attributes

Name
description
Type
string
Description
Description of the group.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. The body of the response is a JSON object containing the created group details.

Request

POST

/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/

POST/v2/group/{group_id}/add-images

Add Images to Group

Add images to a similarity group.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
group_id
Type
string
Description
UUID of the group.
Name
images
Type
array
Description
Array of image UUIDs to add.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed.

Request

POST

/v2/group/{group_id}/add-images

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

POST/v2/group/{group_id}/remove-images

Remove Images From Group

Remove images from a similarity group (not from the workspace).

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
group_id
Type
string
Description
UUID of the group.
Name
images
Type
array
Description
Array of image UUIDs to remove.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed.

Request

POST

/v2/group/{group_id}/remove-images

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

POST/v2/group/{group_id}/add-groups

Add Groups to Group

Add other groups to a similarity group. This allows one group to act as a parent or container for other groups.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
group_id
Type
string
Description
UUID of the target group.
Name
groups
Type
array
Description
An array of group UUIDs to add.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed.

Request

POST

/v2/group/{group_id}/add-groups

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

POST/v2/group/{group_id}/remove-groups

Remove Groups From Group

Remove other groups from a similarity group.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
group_id
Type
string
Description
UUID of the target group.
Name
groups
Type
array
Description
An array of group UUIDs to remove.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed.

Request

POST

/v2/group/{group_id}/remove-groups

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

POST/v2/group/{group_id}/add-objects

Add Objects to Group

Add objects (bounding boxes) to a similarity group.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
group_id
Type
string
Description
UUID of the group.
Name
objects
Type
array
Description
An array of object UUIDs to add.

Optional attributes

Name
workspace
Type
string
Description
UUID of the workspace to use.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed.

Request

POST

/v2/group/{group_id}/add-objects

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

POST/v2/group/{group_id}/remove-objects

Remove Objects From Group

Remove objects from a similarity group.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
group_id
Type
string
Description
UUID of the group.
Name
objects
Type
array
Description
An array of object UUIDs to remove.

Optional attributes

Name
workspace
Type
string
Description
UUID of the workspace to use.

Returns

HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed.

Request

POST

/v2/group/{group_id}/remove-objects

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

Using Different Workspace

When making an API request, the default workspace associated with the user's API token is used. To access data or upload images to a different workspace, you must explicitly specify the workspace – either in the URL (typically for GET requests) or in the JSON payload (typically for POST requests).

Examples

If you want to get all images, types, and tasks from a specific workspace as JSON response:

https://api.ximilar.com/similarity/training/v2/type/?workspace=WORKSPACE_ID
https://api.ximilar.com/similarity/training/v2/task/?workspace=WORKSPACE_ID
https://api.ximilar.com/similarity/training/v2/group/?workspace=WORKSPACE_ID

Uploading/Creating group via POST to a different workspace (requires workspace field):

curl --location 'https://api.ximilar.com/recognition/v2/group/' \
--header 'Authorization: Token __API_TOKEN__' \
--header 'Content-Type: application/json' \
--data '{
    "name": "__NAME__",
    "type":"__TYPE__",
    "workspace": "__WORKSPACE_ID__"
}'