Introduction - Lightdrift

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

Every search endpoint returns the same envelope — a ranked list of results, each carrying the full rights answer:

{
  "query": "sea otter floating on its back",
  "count": 8,
  "latency_ms": 96,
  "results": [
    {
      "asset_id": "inat:41290763",
      "score": 0.83214,
      "title": "Sea Otter, Morro Bay",
      "file": "https://assets.lightdrift.ai/inat/41290763.jpg",
      "license": "cc-by-4.0",
      "rights": { "...": "see Rights answers" },
      "cv": {
        "palette": ["#2b4a5e", "#7fa8b8", "#dce8ec"],
        "luminance": 0.42,
        "neg_space": ["top"],
        "faces": 0,
        "aspect": 1.5
      }
    }
  ]
}

Any search can be constrained on how the image looks, not just what it shows. Pass a filters object:

Filter	Type	Meaning
`luminance_min` / `luminance_max`	number 0–1	Overall brightness.
`monochrome`	boolean	Only (or never) monochrome images.
`faces_min` / `faces_max`	integer	Detected face count.
`aspect_min` / `aspect_max`	number	Width ÷ height.
`neg_space_any`	string[]	Require clean negative space: `left`, `right`, `top`, `bottom`.
`palette_near`	string	Prefer images whose palette sits near this hex color.

Or set parse_design: true and write the intent in plain language — “dark and moody, room for a headline on the left” — and Lightdrift applies the filters for you, reporting what it inferred in applied_design.