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"}'

Every plan includes monthly credits. A search uses 1 credit per 10 results, rounded up, with a minimum of 1. Asset lookups are free. Search by image, image plus text, and /v1/similar require a paid plan. See Plans and limits.

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,
  "credits": {"charged": 1, "remaining": 499, "plan": "free"}
}

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.
credits reports the credits this call used, the credits left on the account, and the plan id. On the Free plan, a request with k above 10 returns 10 results and also carries a notice object with code: "max_results_capped".
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. Need to compare credentials or isolate a connection problem? Use the API and MCP authentication troubleshooting guide.

Getting started

Endpoints

Base URL

Authentication

The response shape

Filters

​Base URL

​Authentication

​The response shape

​Filters

Base URL

Authentication

The response shape

Filters