Configuration

All Spectacles settings live in the Craft CP at Settings → Plugins → Spectacles. API keys should be set in .env and referenced with the $VAR_NAME shorthand.

Quick-start presets

Four buttons at the top of the settings screen pre-fill the form for common scenarios:

• Best quality (Claude + Voyage) — Anthropic Claude for descriptions, Voyage multimodal for embeddings.
• Balanced (OpenAI) — gpt-4o-mini + text-embedding-3-small.
• Cheapest hosted (Gemini) — gemini-2.5-flash + text-embedding-004.
• Self-hosted (Ollama) — llava + nomic-embed-text, no API costs.

Presets only set provider + model names. You still need to drop in your API key and save.

API keys via environment variables

Add to your .env file:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
VOYAGE_API_KEY=pa-...
OLLAMA_BASE_URL=http://host.docker.internal:11434

Then in the settings screen, enter the placeholder (e.g. $OPENAI_API_KEY). Spectacles parses environment variables the same way Craft does, so values never end up in Project Config or version control.

Settings reference

Providers

• Vision provider — which model writes the description, tags, objects, and colors for each image.
• Embedding provider — which model produces the similarity vector. Voyage embeds the image directly; the others embed the description.

Vector index

• Auto (default) — use pgvector if available, otherwise fall back to PHP scan.
• PHP scan — force the JSON-scan backend even on Postgres.
• pgvector — require the pgvector backend; will fail loudly if Postgres + extension isn’t present.

Behavior

• Auto-analyze on upload — queue an analysis job whenever an image is saved.
• Volumes to analyze — restrict Spectacles to specific volumes; leave empty for all volumes.
• Default result limit — how many matches to return per query (overridable per call).
• Minimum similarity score (0–1) — drop matches below this cosine similarity.
• Allow public visitor uploads — when on, exposes POST /spectacles/search.
• Max visitor upload (KB) — request size limit for the public endpoint.

Re-index

After switching providers, click Re-index all images. This queues an analysis job for every image in the configured volumes, regenerating embeddings under the new provider so they’re comparable to new queries.