Platform – Custom Similarity
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
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
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
}
}
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
curl -v -XPOST \
-H 'Authorization: Token __API_TOKEN__' \
-F 'name=__TASK_NAME__' \
https://api.ximilar.com/similarity/training/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
curl -v -XGET \
-H 'Authorization: Token __API_TOKEN__' \
https://api.ximilar.com/similarity/training/v2/task
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
curl -v -XPOST \
-H 'Authorization: Token __API_TOKEN__' \
-F 'name=__TYPE_NAME__' \
https://api.ximilar.com/similarity/training/v2/type
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
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/
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
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__"]}'
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
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__"]}'
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
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__"]}'
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
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__"]}'
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
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__"]}'
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
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__"
}'