Visual Layer Documentation: Visual Intelligence, At Scale

How This Helps

Enrichment runs AI models against your dataset media to unlock advanced capabilities — caption-based search, object detection, face detection, and semantic similarity. Each enrichment operation produces a new dataset copy with the model outputs applied, leaving the original unchanged.

Use status_new for all status checks. The status field is being retired. See Retrieve Dataset Status.

Prerequisites

A Visual Layer Cloud account with API access.
A valid JWT token. See Authentication.
A dataset in READY status with its ID (visible in the browser URL when viewing a dataset: https://app.visual-layer.com/dataset/<dataset_id>/data).

List Available Models

Retrieve the models available for enrichment on a dataset.

GET /api/v1/enrichment/{dataset_id}/list_models
Authorization: Bearer <jwt>

Example

curl -H "Authorization: Bearer <jwt>" \
  "https://app.visual-layer.com/api/v1/enrichment/<dataset_id>/list_models"

Response

Returns an array of model objects. Each object includes:

Field	Description
`id`	The model ID to use when starting enrichment.
`name`	The display name of the model.
`type`	The enrichment type (for example, `CAPTION_IMAGES`, `OBJECT_DETECTION`).
`status`	`Active` or `Coming Soon`. Only `Active` models can be applied.
`vendor`	The model provider (`VL` or `Nvidia`).
`description`	What the model does.
`dependencies`	Other enrichment types that must be applied first, or `null`.

[
  {
    "id": "vl_image_captioner_v00",
    "name": "VL-Image-Captioner",
    "type": "CAPTION_IMAGES",
    "status": "Active",
    "vendor": "VL",
    "description": "Image captioning generates descriptive text that summarizes the content and context of the entire image input.",
    "dependencies": null
  },
  {
    "id": "vl_object_detector_v00",
    "name": "VL-Object-Detector",
    "type": "OBJECT_DETECTION",
    "status": "Active",
    "vendor": "VL",
    "description": "Identifies and locates objects within images or videos by drawing bounding boxes and classifying each detected object.",
    "dependencies": null
  },
  {
    "id": "vl_object_captioner_v00",
    "name": "VL-Object-Captioner",
    "type": "CAPTION_OBJECTS",
    "status": "Active",
    "vendor": "VL",
    "description": "Generates descriptive text summarizing detected objects and their interactions.",
    "dependencies": ["OBJECT_DETECTION"]
  }
]

Check the dependencies field before selecting models. VL-Object-Captioner, for example, requires OBJECT_DETECTION to be applied first.

Check Applied Enrichments

Retrieve the enrichment configuration currently applied to a dataset.

GET /api/v1/enrichment/{dataset_id}/context
Authorization: Bearer <jwt>

Example

curl -H "Authorization: Bearer <jwt>" \
  "https://app.visual-layer.com/api/v1/enrichment/<dataset_id>/context"

Response

{
  "enrichment_context_id": "3666cf3e-af2b-4c6b-b617-c796520de8fd",
  "status": "NEW",
  "dataset_enrichment_models": {
    "enrichment_models": {}
  }
}

A status of NEW means no enrichments have been applied yet. An applied dataset shows the enrichment model IDs in dataset_enrichment_models.enrichment_models.

Start Enrichment

Apply one or more AI models to a dataset. Enrichment creates a new dataset copy with the model outputs applied — the original dataset is not modified.

POST /api/v1/dataset/{dataset_id}/enrich_dataset
Authorization: Bearer <jwt>
Content-Type: application/json

Request Body

{
  "enrichment_models": {
    "<enrichment_type>": "<model_id>"
  }
}

Use the id values from list_models as the model IDs, and the corresponding type values as the keys.

Example

curl -X POST \
  -H "Authorization: Bearer <jwt>" \
  -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"

Response

{
  "dataset_id": "f7a3c120-9913-11f1-b4ca-de29f6ee0a33"
}

The response returns the dataset_id of the new enriched copy. Poll the status endpoint for this new dataset until status_new reaches READY before running search or export operations on it.

The source dataset enters READ ONLY status while enrichment runs. The enriched copy is a separate dataset — it has its own dataset_id and appears as a new entry in your dataset inventory.

Python Example

import requests
import time

VL_BASE_URL = "https://app.visual-layer.com"
JWT_TOKEN = "<your-jwt-token>"
DATASET_ID = "<your-dataset-id>"

headers = {"Authorization": f"Bearer {JWT_TOKEN}"}

# Step 1: List available models
resp = requests.get(
    f"{VL_BASE_URL}/api/v1/enrichment/{DATASET_ID}/list_models",
    headers=headers,
)
resp.raise_for_status()
models = resp.json()
active_models = [m for m in models if m["status"] == "Active"]
print(f"Available models: {[m['name'] for m in active_models]}")

# Step 2: Start enrichment
resp = requests.post(
    f"{VL_BASE_URL}/api/v1/dataset/{DATASET_ID}/enrich_dataset",
    headers=headers,
    json={
        "enrichment_models": {
            "CAPTION_IMAGES": "vl_image_captioner_v00",
            "OBJECT_DETECTION": "vl_object_detector_v00",
        }
    },
)
resp.raise_for_status()
enriched_dataset_id = resp.json()["dataset_id"]
print(f"Enriched dataset ID: {enriched_dataset_id}")

# Step 3: Poll enriched dataset until READY
while True:
    resp = requests.get(
        f"{VL_BASE_URL}/api/v1/dataset/{enriched_dataset_id}",
        headers=headers,
    )
    resp.raise_for_status()
    data = resp.json()
    status = data.get("status_new")
    progress = data.get("progress", 0)
    print(f"  Status: {status} ({progress}%)")
    if status in ("READY", "ERROR"):
        break
    time.sleep(30)

print(f"Enriched dataset ready: {enriched_dataset_id}")

Response Codes

See Error Handling for the error response format and Python handling patterns.

HTTP Code	Meaning
200	Request successful.
401	Unauthorized — check your JWT token.
404	Dataset not found or you do not have access.
409	Conflict — dataset is not in a state that allows enrichment.
500	Internal Server Error — contact support if this persists.

Retrieve Dataset Status

Poll the enriched dataset until processing completes.

Semantic Search

Use caption and semantic embeddings generated by enrichment for search.

API Getting Started

Create a Dataset

Manage Datasets

Search

Guides

Self-Hosted Administration

Useful Scripts

Enrichment

How This Helps

Prerequisites

List Available Models

Example

Response

Check Applied Enrichments

Example

Response

Start Enrichment

Request Body

Example

Response

Python Example

Response Codes

Retrieve Dataset Status

Semantic Search

How This Helps

​Prerequisites

​List Available Models

​Example

​Response

​Check Applied Enrichments

​Example

​Response

​Start Enrichment

​Request Body

​Example

​Response

​Python Example

​Response Codes

​Related Resources

Retrieve Dataset Status

Semantic Search

Prerequisites

List Available Models

Example

Response

Check Applied Enrichments

Example

Response

Start Enrichment

Request Body

Example

Response

Python Example

Response Codes

Related Resources