To search by external query image, upload external the image and make it
available as a query image by issuing the following call:

POST /api/v1/dataset/{dataset-id}/search-image-similarity?entity_type=IMAGES&bounding_box=X,Y,WIDTH,HEIGHT
Headers: Authorization: Bearer <jwt>

​
Request Parameters:

  • file: Query image file
  • bounding_box (optional): X, Y, Width, Height

​
Visual Layer API - Dataset Exploration

After uploading the image you can call exploration endpoint with anchor media id:

GET /api/v1/explore/{dataset-id}

GET /api/v1/explore/{dataset-id}?threshold=0&anchor_type={anchor_type}&entity_type={ENTITY_TYPE}&page_number={PAGE_NUMBER}&anchor_media_id={anchor_media_id}
Headers: Authorization: Bearer <jwt>

​
Query Parameters

  • entity_type IMAGES or OBJECTS
  • anchor_type MEDIA or UPLOAD for when you uploaded the image using the upload endpoint
  • anchor_media_id id of the image you want to use as anchor, returned from the upload for search endpoint
  • threshold similarity threshold(0-4) the search results are clustered according to this value
  • PAGE_NUMBER: Which page of results to view (e.g., 0 for start)

​
Sample Response

  {  
    "clusters": \[  
      {  
        "id": "4e0e4d51-0fef-4fe1-a8ec-1a82b6f4880b", 
        "dataset_id": "95233006-eddc-11ef-b303-76dbc3993eb2",  
        "cluster_type": "IMAGES",  
        "display_name": "Cluster 1",  
        "n_images": 5,  
        "n_objects": 0,  
        "size_bytes": 1024000,  
        "similarity_threshold": 2,  
        "formed_by": "connected_components",  
        "previews": \[  
          {  
            "id": "9e8da312-d954-4844-afc7-357c458c5b03",  
            "image_id": "9e8da312-d954-4844-afc7-357c458c5b03",  
            "image_uri": "/api/v1/image/9e8da312-d954-4844-afc7-357c458c5b03",  
            "width": 800,  
            "height": 600,  
            "image_type": "jpeg",  
            "order": 1,  
            "labels": ["cat", "pet"],  
            "caption": "A gray cat lying on a sofa",  
            "thumbnail_uri": "/api/v1/image/9e8da312-d954-4844-afc7-357c458c5b03/thumbnail"  
          }  
        ],  
        "parent_id": null,  
        "cluster_path": ["4e0e4d51-0fef-4fe1-a8ec-1a82b6f4880b"],  
        "image_order": "similarity"  
      }  
    ]  
  }

​
Example:

curl -H "Authorization: Bearer <jwt>" https://app.visual-layer.com/api/v1/explore/{dataset-id}?threshold=0&entity_type=IMAGES&page_number=0&anchor_media_id={anchor_media_id}

​
**Notes: **

  • Results are paginated with a fixed page size of 100 clusters per page
  • Higher threshold values (0-4 depending on the dataset granularity options) create more granular clusters with stricter similarity requirements
  • When using anchor-based similarity search, results are ordered by similarity to the anchor
  • The entity_type parameter controls whether to return image clusters, object clusters, or both
  • For similarity search with an uploaded image, first use the /search-image-similarity endpoint

More detailed example is here