Skip to main content

​
title: API Introduction description: An introduction to the Visual Layer API

The Visual Layer API provides comprehensive access to search, enrichment, and export capabilities for your visual datasets.

​
Search for Similar Content

Search for similar content using an existing media ID: 
curl -H "Authorization: Bearer <jwt-token>" \
  "https://app.visual-layer.com/api/v1/explore/<dataset-id>?threshold=0&entity_type=IMAGES&page_number=0&anchor_media_id=<media-id>&anchor_type=MEDIA"
Perform semantic vector search using text: 
curl -X POST -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "person wearing a hat",
    "entity_type": "IMAGES",
    "limit": 10
  }' \
  "https://app.visual-layer.com/api/v1/vector_search/<dataset-id>"
Get available embedding models: 
curl -H "Authorization: Bearer <jwt-token>" \
  "https://app.visual-layer.com/api/v1/vector_search/<dataset-id>/embedding_models"

​
Search with Uploaded Images

Upload an image for visual search: 
curl -X POST -H "Authorization: Bearer <jwt-token>" \
  -F "file=@/path/to/search_image.jpg" \
  "https://app.visual-layer.com/api/v1/dataset/<dataset-id>/search-image-similarity?threshold=0&entity_type=IMAGES"
Response: 
{
  "anchor_media_id": "4e0e4d51-0fef-4fe1-a8ec-1a82b6f4880b",
  "anchor_type": "UPLOAD"
}
Then use these values with the exploration API to view results: 
curl -H "Authorization: Bearer <jwt-token>" \
  "https://app.visual-layer.com/api/v1/explore/<dataset-id>?threshold=0&entity_type=IMAGES&page_number=0&anchor_media_id=4e0e4d51-0fef-4fe1-a8ec-1a82b6f4880b&anchor_type=UPLOAD"
You can optionally specify a bounding box to focus search on a specific region: 
curl -X POST -H "Authorization: Bearer <jwt-token>" \
  -F "file=@/path/to/search_image.jpg" \
  "https://app.visual-layer.com/api/v1/dataset/<dataset-id>/search-image-similarity?threshold=0&entity_type=IMAGES&bounding_box={\"x\":0.1,\"y\":0.2,\"width\":0.5,\"height\":0.6}"

​
Enrichment

​
Available Models

List available enrichment models: 
curl -H "Authorization: Bearer <jwt-token>" \
  "https://app.visual-layer.com/api/v1/enrichment/<dataset-id>/list_models"
Get enrichment context for a dataset: 
curl -H "Authorization: Bearer <jwt-token>" \
  "https://app.visual-layer.com/api/v1/enrichment/<dataset-id>/context"

​
Enriching Datasets

Start enrichment with specific models: 
curl -X POST -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enrichment_models": {
      "CAPTION_IMAGES": "vl_image_captioner_v00",
      "OBJECT_DETECTION": "vl_object_detector_v00"
    }
  }' \
  "https://app.visual-layer.com/api/v1/dataset/<dataset-id>/enrich_dataset"
You can also use more detailed model configurations: 
curl -X POST -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enrichment_models": {
      "CAPTION_IMAGES": {
        "id": "moondream2_image_captioner_v00",
        "metadata": {
          "prompt": "Describe this image in detail"
        }
      },
      "OBJECT_DETECTION": "vl_object_detector_v00"
    }
  }' \
  "https://app.visual-layer.com/api/v1/dataset/<dataset-id>/enrich_dataset"
Get preview results of enrichment models: 
curl -X POST -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enrichment_models": {
      "CAPTION_IMAGES": {
        "id": "vl_image_captioner_v00",
        "metadata": {}
      },
      "OBJECT_DETECTION": {
        "id": "vl_object_detector_v00",
        "metadata": {}
      }
    }
  }' \
  "https://app.visual-layer.com/api/v1/enrichment/<dataset-id>/<enrichment-context-id>/previews_enrichment_result"

​
Checking Enrichment Status

Check enrichment status: 
curl -H "Authorization: Bearer <jwt-token>" \
  "https://app.visual-layer.com/api/v1/enrichment/<dataset-id>/<enrichment-context-id>/status"
Abort an enrichment process: 
curl -X DELETE -H "Authorization: Bearer <jwt-token>" \
  "https://app.visual-layer.com/api/v1/enrichment/<dataset-id>/<enrichment-context-id>/abort"

​
Export and Sharing

​
Exporting Content

Export entities asynchronously: 
curl -X POST -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "media_selection": [
      {
        "type": "media",
        "payload": {
          "media_ids": ["9e8da312-d954-4844-afc7-357c458c5b03"]
        }
      }
    ]
  }' \
  "https://app.visual-layer.com/api/v1/dataset/<dataset-id>/export_entities_async?include_images=true&export_format=json"
Export an entire cluster: 
curl -X POST -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "media_selection": [
      {
        "type": "cluster",
        "payload": {
          "cluster_id": "4e0e4d51-0fef-4fe1-a8ec-1a82b6f4880b",
          "cluster_filters": {
            "entity_type": "IMAGES"
          },
          "exclude_media_ids": []
        }
      }
    ]
  }' \
  "https://app.visual-layer.com/api/v1/dataset/<dataset-id>/export_entities_async?include_images=true&export_format=json"

​
Monitoring Export Status

Check export task status: 
curl -H "Authorization: Bearer <jwt-token>" \
  "https://app.visual-layer.com/api/v1/dataset/<dataset-id>/export_status?export_task_id=<export-task-id>"

​
Sharing Views

Create a saved view: 
curl -X POST -H "Authorization: Bearer <jwt-token>" \
  -F "name=Dogs and Cats View" \
  "https://app.visual-layer.com/api/v1/dataset/<dataset-id>/views?labels=[dog,cat]&threshold=0&entity_type=IMAGES"
List saved views: 
curl -H "Authorization: Bearer <jwt-token>" \
  "https://app.visual-layer.com/api/v1/dataset/<dataset-id>/views"
Delete a saved view: 
curl -X DELETE -H "Authorization: Bearer <jwt-token>" \
  "https://app.visual-layer.com/api/v1/dataset/<dataset-id>/views/<view-id>"

​
Error Handling

The API uses standard HTTP status codes to indicate success or failure:
  • 200: Success
  • 400: Bad Request - Check your request parameters
  • 401: Unauthorized - Check your authentication token
  • 404: Not Found - Resource doesn’t exist
  • 500: Internal Server Error - Server-side issue
When an error occurs, the response typically includes details about what went wrong: 
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "name"],
      "msg": "Field required",
      "input": null
    }
  ]
}