Find images, audio and video in your own words

Search your CalmLens media by what it shows or says, from the portal or your own code, and see how the search index is built and kept current.

Keyword search works when you know what an asset is called. Often you only remember what it shows: a red car at night, a dog on a beach, a screenshot of a payment error. CalmLens can now search for assets by description as well as by name, ID and tags, in the portal and through the API.

Search from the portal

Open Search in the portal, or press ⌘K on macOS or Ctrl+K elsewhere, and type a description. Asset results open the asset page. The same dialog also finds portal settings and documentation, so "invite someone" leads to project members and "webhooks" to connector settings and the matching guides. You can narrow the results to All, Settings & features, Docs or Assets, and move through them with the arrow keys and Enter.

The portal waits for a pause in typing before it runs an asset search, so each keystroke doesn't become a query.

Search from your application

The same search is available through the public API and the SDKs:

import { CalmLensClient } from "@calmlens/sdk";

const client = new CalmLensClient({
  apiKey: "your-api-key",
  projectId: "your-project-id"
});

const response = await client.assets.search({
  "query": "a red car at night",
  "mode": "hybrid",
  "limit": 10
});

Each item contains the asset, a score and matchedFields. For AI results, matchedFields includes visual or transcript to show which indexed evidence matched; keyword matches list fields such as name, tags or externalId. A request returns at most 20 results and doesn't paginate. Search returns matching assets, not generated answers, so you can build an image picker or media browser on top of it.

There are three modes:

Hybrid interleaves the two lists instead of sorting by score because the two scoring methods aren't comparable. For the same reason, compare scores only between results from the same method and query.

The API key must belong to the project and have asset read access, and folder permissions apply to every result.

How assets are indexed

Indexing runs in the background, and only assets that are retained, approved and not on safety hold are indexed. A new asset may take a little while to appear in semantic results, and while a project is still being indexed the response reports semanticStatus: "indexing".

For an image, CalmLens embeds the image preview into a shared vector space. For audio, speech is transcribed first and the transcript is embedded. For video, one frame every ten seconds is embedded alongside the speech transcript. Your query is embedded into the same space, and the closest matches come back as results.

Image search is on in every project with no setup, and it includes images that were already in your workspace. Audio and video search is opt-in per project, because media indexing is billed. Media files must be at most 120 seconds and 50 MiB. Audio search covers speech, not music, sound effects or who is speaking. Video sampling can miss a brief scene that falls between frames. Results open the asset rather than jumping to a timestamp.

Keeping the index in step

Each index entry is tied to a specific content revision. If an asset's content is replaced, results from the old revision are ignored until the new one is indexed. An hourly reconciliation job repairs missing entries and retries indexing that failed.

The index stores vectors and revision details, not another copy of your media. Removing an asset's content, deleting the asset or deleting the project removes its vectors. Semantic results also exclude rejected, safety-held and removed assets at query time, and they reflect your current permissions rather than those at indexing time.

When semantic search is unavailable

If the semantic service can't be reached, a hybrid request still returns keyword results, with semanticStatus: "unavailable". A semantic request returns no results in that case. Settings and docs search in the portal run independently and keep working. When semanticStatus is disabled, the request ran in keyword-only mode.

Turning on audio and video search

In project settings, turn on Search audio and video. Before you save, the portal shows an estimate of the initial indexing cost for the project's existing audio and video. Turning it off later removes audio and video from the index and leaves images searchable. Turning it back on rebuilds the media index without charging again for content that was already indexed. Changing the setting requires project settings write permission.

Pricing

Keyword, settings and docs search are free, and so is indexing images. Semantic and hybrid asset searches are billed per 1,000 completed queries. Media indexing is billed per started six seconds of audio or video, once per content revision, and automatic repairs don't charge again. Search usage appears in your project's usage page. The search guide's billing section lists the current rates and exactly what counts as a query.

Read the search guide for the full API details, availability states and setup steps.