Search

Search with natural language

Default photo search is live on Voyage: voyage-multimodal-3.5 embeds each indexed image together with its caption into a 1,024-dimensional vector. At query time, semantic retrieval and caption keyword matching select candidates, then rerank-3 ranks their text for the query. The launch index contains 1,852,370 captioned images, including stock photography and specialist sources. Describe what matters for your use: subject, recognizable names, visible text, era, aesthetic, mood, lighting, composition, or space for a headline. Captions improve retrieval but can contain mistakes; inspect the image and its source when exact identification matters.

curl https://api.lightdrift.ai/v1/search \
  -H "X-API-Key: $LIGHTDRIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"a red Mini Cooper parked on a city street","k":5}'

The response includes query_id, results, backend, mode, ranking, reranked, pool_size, latency_ms, timing_ms, and credits. Each result includes an asset ID, file URLs, dimensions, source, license information, and attribution. A normal Voyage search reports backend: "voyage" and ranking: "text". The credits object reports what the call cost and what is left: {"charged": 1, "remaining": 499, "plan": "free"}. Use the API reference for field shapes. Search latency excludes downloading and rendering result images. Provider and network conditions vary; there is no fixed latency guarantee.

Modes

Mode	Behavior
`auto` (default)	Text: caption reranking. Image-only: similarity. Image plus text: joint-embedding similarity blended with caption text reranking.
`text`	Force caption text reranking. Requires query text; an image still influences candidate retrieval.
`none`	Skip reranking on the selected retrieval path. Default photo requests still use Voyage query embeddings; this is not a promise of no model call.

All search modes use the same Voyage index. Old mode:visual requests are accepted as auto; rerank_text is retained for compatibility but no longer changes the backend. Graphics-related queries search the current captioned collection, without switching to the old index.

Request controls

Field	Type	Default	Purpose
`query`	string	optional with an image	Natural-language query, up to 1000 characters; `q` is an alias.
`image_base64`	string	omitted	JPEG, PNG or WebP upload as raw base64 or a data URL.
`image_url`	string	omitted	Public HTTPS image URL. Use this or image_base64, not both.
`k`	integer 1–100	10	Results to return; `top_k` is an alias. Each 10 results cost 1 credit, rounded up. On the Free plan, values above 10 are capped to 10 and the response carries a `notice`.
`ann_k`	integer 1–1000	100	Semantic retrieval candidates.
`bm25_k`	integer 0–1000	50	Caption keyword candidates; zero disables this lane.
`ann_ef`	integer 64–4096	2048	Accepted for compatibility; ignored by the current retrieval store.
`rerank_k`	integer 1–100, or null	60	Candidates to rerank. Null uses the standard maximum of 100; larger explicit values are rejected before billing.
`rerank_text`	boolean	true	Deprecated compatibility field; does not change retrieval or reranking.
`explain`	boolean	false	Include ranking details; also enabled for `mode:none`.
`filters`	object	default filters below	Constrain retrieval before ranking.
`client_session`	string	omitted	Link related calls from one agent session.

The playground exposes the same modes, but may choose a larger result/rerank count for its grid. /v1/health reports API defaults. Start with defaults; increase candidate counts only when useful for your queries.

Defaults you get without asking

Three filters are applied whenever you leave them out, because most callers want them and forgetting them produced the worst results in our own evaluations:

Filter	Default	Why
`ai_generated`	`false`	Exclude assets marked AI-generated. All records in the current captioned index are marked non-AI-generated; this does not imply all are photographs.
`commercial`	`true`	Only licences that permit commercial use. Noncommercial licences are opt-in.
`min_width`	`1000`	Files at least 1000 px wide. If that leaves a page short, the search is retried once without it and the response carries `"relaxed": ["min_width"]`.

To opt out of a default, send the key with null: {"filters": {"ai_generated": null}} removes the AI-generation restriction; it does not add assets outside the current index. Every result carries ai_generated so you can badge it. Results are also de-duplicated: when the same file is indexed under two sources (a Flickr photo also collected by a second Flickr crawl, or a CC0 stock image mirrored on two stock sites) only the highest-ranked copy is shown.

Filters

Filters constrain retrieval before ranking. Omitted default filters still apply as described above. The playground lists the 17 sources present in the current captioned index. Its “Any size” selection explicitly removes the width minimum, and unchecking “Commercial use only” includes noncommercial licenses. The explicit-content control uses nsfw_max:0.2; turning it off sends null. Unknown scores remain eligible. Color treatment uses measured metadata; records without that metadata are excluded when a specific treatment is selected. Format matching accepts case and extension aliases such as JPEG, jpeg, and jpg. Image format refers to the indexed original, not necessarily the thumbnail format.

Filter	Type	Meaning
`commercial`	boolean	Only assets whose declared license permits commercial use. Defaults to `true`; send `null` to include noncommercial licences.
`attribution_required`	boolean	Only assets that do (`true`) or do not (`false`) require attribution.
`derivatives`	boolean	Only assets whose license permits derivative works.
`license_id`	string[]	Restrict to these licenses: `cc0`, `pdm`, `us-gov-pd`, `cc-by`, `cc-by-sa`, `cc-by-nd`, `cc-by-nc`, `cc-by-nc-sa`, `cc-by-nc-nd`, `mit`, `apache-2.0`, `isc`, `ofl`.
`source`	string[]	Restrict to these sources: `inat`, `yfcc`, `flickr`, `wikimedia`, `wm_quality`, `smithsonian`, `nasa`, `govflickr`, …
`min_width` / `min_height`	integer	Minimum pixel dimensions of the full-resolution file. `min_width` defaults to 1000 (relaxed automatically if the page comes up short); send `null` to disable.
`orientation`	`landscape` \| `portrait` \| `square`	Aspect class.
`format`	string[]	e.g. `["jpeg", "png"]`.
`year_min` / `year_max`	integer	Capture or creation year, where the source declares one.
`monochrome`	boolean	Only (or never) monochrome images.
`colors`	string[]	Dominant named colours: `black`, `white`, `gray`, `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `navy`, `purple`, `pink`, `brown`, `beige`, `cream`. Available where palette metadata exists.
`ai_generated`	boolean	Exclude (`false`, the default) or select (`true`) assets the source marks as AI-generated; `null` returns both.
`nsfw_max`	number 0–1	Maximum permitted NSFW score. Default `0.2`; assets without a score pass.

Search with an image

Search by image and image plus text search are available on paid plans (Starter and above). On the Free plan these requests return 403 with "error": "paid_feature" and an upgrade link. The playground allows 10 free searches per day on every plan, including image search, so you can try it first. See Plans and limits.

Use the same /v1/search endpoint for image-only or image-plus-text search. Supply at least text or one image. Uploaded/reference images are query inputs; they are not added to the searchable collection. Public image URL plus text:

{
  "image_url": "https://your-public-host.example/reference.jpg",
  "query": "blue car",
  "k": 5
}

Omit query for image-only search. For local files, send image_base64 as raw base64 or a data URL instead of image_url:

import base64
import os
from pathlib import Path
import requests

response = requests.post(
    "https://api.lightdrift.ai/v1/search",
    headers={"X-API-Key": os.environ["LIGHTDRIFT_API_KEY"]},
    json={
        "image_base64": base64.b64encode(Path("reference.jpg").read_bytes()).decode(),
        "query": "blue car",
        "k": 5,
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

JPEG, PNG and WebP still images are supported, up to 5 MiB decoded and 20 megapixels. Images are oriented, resized to a maximum 1024-pixel edge, stripped of metadata, and sent to Voyage. URLs must use public HTTPS on port 443, with no embedded credentials; private addresses are blocked and redirects are checked. Invalid inputs return 422; oversized request bodies return 413. Failed searches are not charged. Image searches use the same credit rule as text searches: 1 credit per 10 results, rounded up. The playground’s image attachment button accepts local files, previews the reference, and allows optional text. Clear the text for image-only search. Images MCP accepts the same image_base64 and image_url fields through search_images; reconnect clients to refresh tool schemas. Responses identify query_type as text, image, or image_text. In auto mode, image-only returns ranking:image without text reranking. Image-plus-text returns ranking:multimodal: reciprocal-rank fusion gives joint-embedding similarity 65% weight and caption text ranking 35%. These are rank scores, not probabilities. Added text steers retrieval; this does not edit or generate an image, or guarantee exact constraints. mode:text forces text ranking, and mode:none skips reranking. A reranker failure returns an explicitly degraded response. Raw query images and source URLs are not persisted in search logs. Search logs retain the query text, query type and a fingerprint of the normalized image; query embeddings may be cached for up to one hour.

Similar images

Use /v1/similar for an existing indexed asset ID. Use /v1/search above for a new image upload. Find similar is a paid plan feature; on the Free plan it returns 403 with "error": "paid_feature". It uses the same credit rule as search.

curl https://api.lightdrift.ai/v1/similar \
  -H "X-API-Key: $LIGHTDRIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_id":"isorepublic:17191","k":5}'

For a Voyage-indexed seed, similarity uses its saved joint image-and-caption vector and excludes the seed from the results. Similar results are returned in retrieval order. Seeds outside the current index, removed assets and unavailable assets return 404; no legacy search fallback is used.

Files and rights

GET /v1/asset/{asset_id} returns metadata and file URLs. Use the returned thumb or file URL to fetch an image; delivery is separate from the search request. URLs include the query ID so downloads can be attributed to their search. Existing legacy asset links remain supported. Licenses and permission flags come from source metadata. A caption is not proof of identity, permission, or a model/property release. See Rights answers.

Readiness and errors

Default Voyage photo search does not start a Lightdrift GPU. GET /v1/warm reports the selected backend, configuration readiness, and recent provider successes; key presence is not proof that a fresh provider request will succeed. GET /v1/health?deep=true checks database/index connectivity. Actual searches are the end-to-end availability check. Search no longer uses the legacy GPU service. Temporary Voyage provider failures return an availability error; retry according to Retry-After.

Status	Meaning and action
`401`	Missing or invalid API key.
`402`	`credits_exhausted`: the plan’s monthly credits are used up. Upgrade, wait for the monthly reset, or on Scale and Custom buy a credit pack.
`403`	`paid_feature`: search by image, image plus text, or find similar on the Free plan. Upgrade to a paid plan.
`404`	Asset or usable seed unavailable.
`422`	Invalid fields or incompatible mode controls.
`429`	Account/key rate or concurrency limit; honor `Retry-After`.
`502` / `503`	Search, provider, or authentication dependency unavailable. Honor `Retry-After` and use bounded backoff. Failed searches are not charged.

A successful response can include degraded: "reranker unavailable; lane-order results". It contains retrieval-order results, with null rerank scores, and is still a successful search that uses credits. Inspect this field if reranked ordering is essential. Send a stable Idempotency-Key for retries of the same logical request to avoid duplicate search charges. Do not reuse it for different queries.

Billing and limits

Each successful API or MCP search or find-similar call uses 1 credit per 10 results, rounded up, with a minimum of 1. A search for 10 or fewer results uses 1 credit; a search for 100 results uses 10. Asset lookups (GET /v1/asset/...) are free, and failed searches are not charged. Every plan includes monthly credits, starting with 500 free credits every month on the Free plan. The signed-in playground has a separate allowance of 10 free searches per day. See Plans and limits for plans, credits, request limits, and concurrency limits.

Get started

Learn

Account

Core concepts

Search with natural language

Modes

Request controls

Defaults you get without asking

Filters

Search with an image

Similar images

Files and rights

Readiness and errors

Billing and limits