Usage

Re-index existing assets

If you installed Spectacles into a site that already has image assets, open the settings screen and click Re-index all images. This queues an analysis job for every image in the configured volumes. Progress shows in the Craft queue.

Twig helpers

Similar to a given asset

{% set similar = craft.spectacles.similar(asset, 8) %}
{% for row in similar %}
  <a href="{{ row.asset.url }}">
    <img src="{{ row.asset.url({ width: 240, height: 240, mode: 'crop' }) }}">
    <small>{{ row.score }} — {{ row.metadata.description }}</small>
  </a>
{% endfor %}

Free-form text search

{% for row in craft.spectacles.searchText('foggy mountain at sunrise') %}
  <img src="{{ row.asset.url }}">
{% endfor %}

Inspect metadata directly

{% set meta = craft.spectacles.metadataFor(asset) %}
{{ meta.description }}
{{ meta.tags|join(', ') }}
{{ meta.embeddingModel }}

Visitor upload form

A drop-in partial is included. Add it to any front-end template:

{% include 'spectacles/_partials/upload-form' %}

The partial ships with an unstyled <form> + a small vanilla-JS handler. Visitors upload an image; Spectacles returns the analysis and the closest matches as JSON. Add your own styles around the form to match your site.

JSON endpoint

Or post to the endpoint directly:

POST /spectacles/search
Content-Type: multipart/form-data
Accept: application/json

image=<file>

Response:

{
  "analysis": {
    "description": "A foggy mountain ridge at sunrise.",
    "tags": ["mountain", "fog", "sunrise"],
    "objects": ["mountain", "trees"],
    "colors": ["pink", "blue", "gray"]
  },
  "results": [
    { "id": 412, "url": "...", "thumbUrl": "...", "score": 0.87, "description": "..." }
  ]
}

Similar by asset id

GET /spectacles/similar/{assetId}
Accept: application/json

CP sidebar

Every image asset’s edit page in the Control Panel gets a Spectacles panel in the sidebar showing:

The AI-generated description
Tags as inline tokens
Up to 8 similar-image thumbnails (each links to its own edit page)
The active vector backend (scan or pgvector) and embedding model

For assets that haven’t been analyzed yet, the panel shows a single Analyze now button that queues a one-off analysis job.