Search captioned images

curl --request POST \
  --url https://api.lightdrift.ai/v1/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "",
  "k": 10,
  "ann_k": 100,
  "bm25_k": 50,
  "ann_ef": 2048,
  "mode": "auto",
  "rerank": true,
  "rerank_k": 60,
  "rerank_text": true,
  "explain": false,
  "filters": {
    "commercial": true,
    "attribution_required": true,
    "derivatives": true,
    "license_id": [
      "<string>"
    ],
    "source": [
      "<string>"
    ],
    "min_width": 123,
    "min_height": 123,
    "orientation": "<string>",
    "colors": [
      "<string>"
    ],
    "monochrome": true,
    "year_min": 123,
    "year_max": 123,
    "ai_generated": true,
    "nsfw_max": 0.2,
    "format": [
      "<string>"
    ]
  },
  "include_graphics": true,
  "client_session": "<string>",
  "experiment": "<string>",
  "image_base64": "<string>",
  "image_url": "<string>"
}
'

import requests

url = "https://api.lightdrift.ai/v1/search"

payload = {
    "query": "",
    "k": 10,
    "ann_k": 100,
    "bm25_k": 50,
    "ann_ef": 2048,
    "mode": "auto",
    "rerank": True,
    "rerank_k": 60,
    "rerank_text": True,
    "explain": False,
    "filters": {
        "commercial": True,
        "attribution_required": True,
        "derivatives": True,
        "license_id": ["<string>"],
        "source": ["<string>"],
        "min_width": 123,
        "min_height": 123,
        "orientation": "<string>",
        "colors": ["<string>"],
        "monochrome": True,
        "year_min": 123,
        "year_max": 123,
        "ai_generated": True,
        "nsfw_max": 0.2,
        "format": ["<string>"]
    },
    "include_graphics": True,
    "client_session": "<string>",
    "experiment": "<string>",
    "image_base64": "<string>",
    "image_url": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: '',
    k: 10,
    ann_k: 100,
    bm25_k: 50,
    ann_ef: 2048,
    mode: 'auto',
    rerank: true,
    rerank_k: 60,
    rerank_text: true,
    explain: false,
    filters: {
      commercial: true,
      attribution_required: true,
      derivatives: true,
      license_id: ['<string>'],
      source: ['<string>'],
      min_width: 123,
      min_height: 123,
      orientation: '<string>',
      colors: ['<string>'],
      monochrome: true,
      year_min: 123,
      year_max: 123,
      ai_generated: true,
      nsfw_max: 0.2,
      format: ['<string>']
    },
    include_graphics: true,
    client_session: '<string>',
    experiment: '<string>',
    image_base64: '<string>',
    image_url: '<string>'
  })
};

fetch('https://api.lightdrift.ai/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "query_id": "q_33b7214c7da1a07ce4355a40",
  "results": [
    {
      "asset_id": "isorepublic:17191",
      "score": 0.921875,
      "title": "Mini in Brooklyn",
      "source": "isorepublic",
      "ai_generated": false,
      "width": 4000,
      "height": 2667,
      "file": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/isorepublic:17191",
      "thumb": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/isorepublic:17191?v=thumb",
      "rights": {
        "license": "cc0",
        "license_verbatim": "CC0 1.0",
        "commercial": true,
        "attribution_required": false,
        "derivatives": true,
        "share_alike": false,
        "attribution": null,
        "provenance_url": "https://isorepublic.com/photo/mini-in-brooklyn/",
        "basis": "as-declared by source; verify for critical use"
      }
    },
    {
      "asset_id": "flickr:51141533761",
      "score": 0.90234375,
      "title": "Night in the city-2",
      "source": "flickr",
      "ai_generated": false,
      "width": 1023,
      "height": 968,
      "file": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/flickr:51141533761",
      "thumb": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/flickr:51141533761?v=thumb",
      "rights": {
        "license": "cc-by-sa",
        "license_verbatim": "CC BY-SA 2.0",
        "commercial": true,
        "attribution_required": true,
        "derivatives": true,
        "share_alike": true,
        "attribution": "\"Night in the city-2\" by Tatiana El-Bakri, flickr, CC BY-SA",
        "provenance_url": "https://www.flickr.com/photos/189281045@N03/51141533761",
        "basis": "as-declared by source; verify for critical use"
      }
    },
    {
      "asset_id": "yfcc:9715466326",
      "score": 0.85546875,
      "title": "MINIPalooza 2013",
      "source": "yfcc",
      "ai_generated": false,
      "width": 1024,
      "height": 575,
      "file": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/yfcc:9715466326",
      "thumb": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/yfcc:9715466326?v=thumb",
      "rights": {
        "license": "cc-by",
        "license_verbatim": "by <>",
        "commercial": true,
        "attribution_required": true,
        "derivatives": true,
        "share_alike": false,
        "attribution": "\"MINIPalooza 2013\" by unknown, yfcc, CC BY 4.0/3.0/2.0",
        "provenance_url": "http://www.flickr.com/photos/101530550@N05/9715466326/",
        "basis": "as-declared by source; verify for critical use"
      }
    },
    {
      "asset_id": "yfcc:9958535786",
      "score": 0.85546875,
      "title": "Study in Blue - Phibsboro [Dublin] - 89 Phibsborough Road",
      "source": "yfcc",
      "ai_generated": false,
      "width": 1023,
      "height": 697,
      "file": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/yfcc:9958535786",
      "thumb": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/yfcc:9958535786?v=thumb",
      "rights": {
        "license": "cc-by-sa",
        "license_verbatim": "by-sa <>",
        "commercial": true,
        "attribution_required": true,
        "derivatives": true,
        "share_alike": true,
        "attribution": "\"Study in Blue - Phibsboro [Dublin] - 89 Phibsborough Road\" by unknown, yfcc, CC BY-SA",
        "provenance_url": "http://www.flickr.com/photos/80824546@N00/9958535786/",
        "basis": "as-declared by source; verify for critical use"
      }
    },
    {
      "asset_id": "wm_quality:194126027",
      "score": 0.8359375,
      "title": "AC BD Lochnerstraße 21.jpg",
      "source": "wm_quality",
      "ai_generated": false,
      "width": 2581,
      "height": 3226,
      "file": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/wm_quality:194126027",
      "thumb": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/wm_quality:194126027?v=thumb",
      "rights": {
        "license": "cc-by-sa",
        "license_verbatim": "CC BY-SA 4.0",
        "commercial": true,
        "attribution_required": true,
        "derivatives": true,
        "share_alike": true,
        "attribution": "\"AC BD Lochnerstraße 21.jpg\" by Grunpfnul, wm_quality, CC BY-SA",
        "provenance_url": "https://commons.wikimedia.org/wiki/File:AC_BD_Lochnerstra%C3%9Fe_21.jpg",
        "basis": "as-declared by source; verify for critical use"
      }
    }
  ],
  "latency_ms": 439,
  "timing_ms": {
    "embed": 180,
    "retrieve": 70,
    "rerank": 161
  },
  "mode": "text",
  "ranking": "text",
  "pool_size": 131,
  "reranked": 60,
  "backend": "voyage"
}

POST

Search captioned images

curl --request POST \
  --url https://api.lightdrift.ai/v1/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "",
  "k": 10,
  "ann_k": 100,
  "bm25_k": 50,
  "ann_ef": 2048,
  "mode": "auto",
  "rerank": true,
  "rerank_k": 60,
  "rerank_text": true,
  "explain": false,
  "filters": {
    "commercial": true,
    "attribution_required": true,
    "derivatives": true,
    "license_id": [
      "<string>"
    ],
    "source": [
      "<string>"
    ],
    "min_width": 123,
    "min_height": 123,
    "orientation": "<string>",
    "colors": [
      "<string>"
    ],
    "monochrome": true,
    "year_min": 123,
    "year_max": 123,
    "ai_generated": true,
    "nsfw_max": 0.2,
    "format": [
      "<string>"
    ]
  },
  "include_graphics": true,
  "client_session": "<string>",
  "experiment": "<string>",
  "image_base64": "<string>",
  "image_url": "<string>"
}
'

import requests

url = "https://api.lightdrift.ai/v1/search"

payload = {
    "query": "",
    "k": 10,
    "ann_k": 100,
    "bm25_k": 50,
    "ann_ef": 2048,
    "mode": "auto",
    "rerank": True,
    "rerank_k": 60,
    "rerank_text": True,
    "explain": False,
    "filters": {
        "commercial": True,
        "attribution_required": True,
        "derivatives": True,
        "license_id": ["<string>"],
        "source": ["<string>"],
        "min_width": 123,
        "min_height": 123,
        "orientation": "<string>",
        "colors": ["<string>"],
        "monochrome": True,
        "year_min": 123,
        "year_max": 123,
        "ai_generated": True,
        "nsfw_max": 0.2,
        "format": ["<string>"]
    },
    "include_graphics": True,
    "client_session": "<string>",
    "experiment": "<string>",
    "image_base64": "<string>",
    "image_url": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: '',
    k: 10,
    ann_k: 100,
    bm25_k: 50,
    ann_ef: 2048,
    mode: 'auto',
    rerank: true,
    rerank_k: 60,
    rerank_text: true,
    explain: false,
    filters: {
      commercial: true,
      attribution_required: true,
      derivatives: true,
      license_id: ['<string>'],
      source: ['<string>'],
      min_width: 123,
      min_height: 123,
      orientation: '<string>',
      colors: ['<string>'],
      monochrome: true,
      year_min: 123,
      year_max: 123,
      ai_generated: true,
      nsfw_max: 0.2,
      format: ['<string>']
    },
    include_graphics: true,
    client_session: '<string>',
    experiment: '<string>',
    image_base64: '<string>',
    image_url: '<string>'
  })
};

fetch('https://api.lightdrift.ai/v1/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "query_id": "q_33b7214c7da1a07ce4355a40",
  "results": [
    {
      "asset_id": "isorepublic:17191",
      "score": 0.921875,
      "title": "Mini in Brooklyn",
      "source": "isorepublic",
      "ai_generated": false,
      "width": 4000,
      "height": 2667,
      "file": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/isorepublic:17191",
      "thumb": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/isorepublic:17191?v=thumb",
      "rights": {
        "license": "cc0",
        "license_verbatim": "CC0 1.0",
        "commercial": true,
        "attribution_required": false,
        "derivatives": true,
        "share_alike": false,
        "attribution": null,
        "provenance_url": "https://isorepublic.com/photo/mini-in-brooklyn/",
        "basis": "as-declared by source; verify for critical use"
      }
    },
    {
      "asset_id": "flickr:51141533761",
      "score": 0.90234375,
      "title": "Night in the city-2",
      "source": "flickr",
      "ai_generated": false,
      "width": 1023,
      "height": 968,
      "file": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/flickr:51141533761",
      "thumb": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/flickr:51141533761?v=thumb",
      "rights": {
        "license": "cc-by-sa",
        "license_verbatim": "CC BY-SA 2.0",
        "commercial": true,
        "attribution_required": true,
        "derivatives": true,
        "share_alike": true,
        "attribution": "\"Night in the city-2\" by Tatiana El-Bakri, flickr, CC BY-SA",
        "provenance_url": "https://www.flickr.com/photos/189281045@N03/51141533761",
        "basis": "as-declared by source; verify for critical use"
      }
    },
    {
      "asset_id": "yfcc:9715466326",
      "score": 0.85546875,
      "title": "MINIPalooza 2013",
      "source": "yfcc",
      "ai_generated": false,
      "width": 1024,
      "height": 575,
      "file": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/yfcc:9715466326",
      "thumb": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/yfcc:9715466326?v=thumb",
      "rights": {
        "license": "cc-by",
        "license_verbatim": "by <>",
        "commercial": true,
        "attribution_required": true,
        "derivatives": true,
        "share_alike": false,
        "attribution": "\"MINIPalooza 2013\" by unknown, yfcc, CC BY 4.0/3.0/2.0",
        "provenance_url": "http://www.flickr.com/photos/101530550@N05/9715466326/",
        "basis": "as-declared by source; verify for critical use"
      }
    },
    {
      "asset_id": "yfcc:9958535786",
      "score": 0.85546875,
      "title": "Study in Blue - Phibsboro [Dublin] - 89 Phibsborough Road",
      "source": "yfcc",
      "ai_generated": false,
      "width": 1023,
      "height": 697,
      "file": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/yfcc:9958535786",
      "thumb": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/yfcc:9958535786?v=thumb",
      "rights": {
        "license": "cc-by-sa",
        "license_verbatim": "by-sa <>",
        "commercial": true,
        "attribution_required": true,
        "derivatives": true,
        "share_alike": true,
        "attribution": "\"Study in Blue - Phibsboro [Dublin] - 89 Phibsborough Road\" by unknown, yfcc, CC BY-SA",
        "provenance_url": "http://www.flickr.com/photos/80824546@N00/9958535786/",
        "basis": "as-declared by source; verify for critical use"
      }
    },
    {
      "asset_id": "wm_quality:194126027",
      "score": 0.8359375,
      "title": "AC BD Lochnerstraße 21.jpg",
      "source": "wm_quality",
      "ai_generated": false,
      "width": 2581,
      "height": 3226,
      "file": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/wm_quality:194126027",
      "thumb": "https://api.lightdrift.ai/v1/asset/q_33b7214c7da1a07ce4355a40/wm_quality:194126027?v=thumb",
      "rights": {
        "license": "cc-by-sa",
        "license_verbatim": "CC BY-SA 4.0",
        "commercial": true,
        "attribution_required": true,
        "derivatives": true,
        "share_alike": true,
        "attribution": "\"AC BD Lochnerstraße 21.jpg\" by Grunpfnul, wm_quality, CC BY-SA",
        "provenance_url": "https://commons.wikimedia.org/wiki/File:AC_BD_Lochnerstra%C3%9Fe_21.jpg",
        "basis": "as-declared by source; verify for critical use"
      }
    }
  ],
  "latency_ms": 439,
  "timing_ms": {
    "embed": 180,
    "retrieve": 70,
    "rerank": 161
  },
  "mode": "text",
  "ranking": "text",
  "pool_size": 131,
  "reranked": 60,
  "backend": "voyage"
}

Authorizations

X-API-Key

string

header

required

Your Lightdrift API key. Usage is metered per query.

Headers

Idempotency-Key

string

default:""

Body

application/json

Provide query text, one reference image, or both. image_base64 and image_url are mutually exclusive.

query

string

default:""

Maximum string length: 1000

integer

default:10

Required range: 1 <= x <= 100

ann_k

integer

default:100

Required range: 1 <= x <= 1000

bm25_k

integer

default:50

Required range: 0 <= x <= 1000

ann_ef

integer

default:2048

Required range: 64 <= x <= 4096

mode

enum<string>

default:auto

auto: text reranking for text, image similarity for image-only, fused similarity and text reranking for image-plus-text. text requires query text and forces caption reranking. none skips reranking.

Available options:

auto,

none,

text

rerank

boolean | null

rerank_k

integer | null

default:60

Required range: 1 <= x <= 500

rerank_text

boolean

default:true

explain

boolean

default:false

filters

Filters · object

Show child attributes

include_graphics

boolean | null

client_session

string | null

experiment

string | null

image_base64

string

JPEG, PNG or WebP base64 data URL or raw base64. Maximum 5 MiB decoded, 20 megapixels; still images only. Resized to a 1024-pixel edge before embedding.

Maximum string length: 6990572

image_url

string

Public HTTPS image URL on port 443, without embedded credentials. Same image limits; private addresses blocked. Use this or image_base64, not both.

Maximum string length: 4096

Response

Search results and source-declared rights.

query_id

string

results

object[]

Show child attributes

latency_ms

integer

timing_ms

object

Show child attributes

mode

string

ranking

string

text, image, multimodal, none, or none (degraded). Multimodal scores fuse similarity and text ranks; scores are not probabilities.

pool_size

integer

reranked

integer

backend

string

Search responses report voyage.

degraded

string

Reranker unavailable; results are in retrieval order. Successful billed response.

relaxed

string[]

Default filters relaxed to fill results; explicit constraints are not relaxed.

query_type

enum<string>

Input modality for /v1/search.

Available options:

text,

image,

image_text

Getting started

Endpoints

Search captioned images

Authorizations

Headers

Body

Response