Platform - Custom Similarity

BasicsQuickstartXimilar PlatformVideo Tutorials

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

The 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 can be 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.

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

Extract visual descriptors/embeddings for images. This endpoint is used to get the vector representation of images that can be used for similarity search. You can use either a collection ID or a task ID with version to specify which model to use for extraction.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    records
    Type
    array
    Description

    Array of image records to process. Each record must contain either _url or _base64 field.

Optional attributes

  • 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. Body of the response 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. 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=__YOUR_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. Body of the response 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.

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. 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=__YOUR_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 can contain only images or only groups.

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

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.

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

    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

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

    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

    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

Getting all images, types, tasks from specific workspace:

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

Was this page helpful?