Introduction

Base URL

https://api.lightdrift.ai

Authentication

Pass your API key in the X-API-Key header on every request:

curl https://api.lightdrift.ai/v1/search \
  -H "X-API-Key: $LIGHTDRIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "sea otter floating on its back"}'

Billing is per query. There are no seats and no minimums.

The response shape

/v1/search and /v1/similar return the same envelope — a ranked list of results, each carrying the full rights answer:

{
  "query_id": "q_e6458536ccdc445b",
  "results": [
    {
      "asset_id": "govflickr:8412901414",
      "score": 0.7518,
      "title": null,
      "source": "govflickr",
      "width": 1024,
      "height": 768,
      "file": "https://api.lightdrift.ai/v1/asset/q_e6458536ccdc445b/govflickr:8412901414",
      "thumb": "https://api.lightdrift.ai/v1/asset/q_e6458536ccdc445b/govflickr:8412901414?v=thumb",
      "rights": {
        "...": "see Rights answers"
      }
    }
  ],
  "backend": "voyage",
  "mode": "auto",
  "ranking": "text",
  "latency_ms": 5965
}

query_id ties every file fetch back to the query that produced it. Keep it.
score is the reranker’s relevance score, higher is better, not a calibrated probability. Similar-image searches use retrieval similarity; skipped reranking can return null. It is also null on the rare response that also carries "degraded": "reranker unavailable; lane-order results" — results are still valid, just ordered by retrieval rank instead of rerank.
file and thumb are tracked URLs: a GET answers 302 to a signed download link valid for one hour. Follow redirects.

Filters

Filters constrain retrieval before ranking. Omitted commercial, AI-generation, width and NSFW fields retain their API defaults; see Search defaults. Pass null where supported to remove a default.

Filter	Type	Meaning
`commercial`	boolean	Only assets whose declared license permits commercial use. Defaults to true; null removes this restriction.
`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, e.g. `["cc0", "cc-by", "pdm"]`.
`source`	string[]	Restrict to these sources, e.g. `["inat", "wikimedia"]`.
`min_width` / `min_height`	integer	Minimum pixel dimensions of the full-resolution file.
`orientation`	`landscape` \| `portrait` \| `square`	Aspect class.
`format`	string[]	File formats, 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 (`red`, `navy`, `cream`, …). Present only where an image has a clear dominant palette, coverage varies by source.
`ai_generated`	boolean	Select or exclude assets the source marks as AI-generated.
`nsfw_max`	number 0–1	Maximum permitted NSFW score. Default `0.2`; assets without a score pass.

See Searching the index for every filter with examples. Describe mood, style, composition and intended use in the natural-language query. These are semantic requests, not guaranteed hard filters. You can also supply a reference image using image_base64 or a public HTTPS image_url, with optional text to refine the search. See image search examples for supported formats, limits, and request payloads.

Getting started

Endpoints

Base URL

Authentication

The response shape

Filters

​Base URL

​Authentication

​The response shape

​Filters

Base URL

Authentication

The response shape

Filters