Skip to main content
POST
Search captioned images

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
k
integer
default:10

Results to return. Each 10 results use 1 credit, rounded up. The Free plan returns at most 10; larger values are capped and the response carries a notice.

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

Rerank up to 100 candidates; default 60. Null uses 100. Larger values are rejected before billing.

Required range: 1 <= x <= 100
rerank_text
boolean
default:true
explain
boolean
default:false
filters
Filters · object
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. Requires a paid plan; returns 403 paid_feature on Free.

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. Requires a paid plan; returns 403 paid_feature on Free.

Maximum string length: 4096

Response

Search results and source-declared rights.

query_id
string
results
object[]
latency_ms
integer
timing_ms
object
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. This is a successful response and uses credits.

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
credits
object

Credits used by this call and credits left on the account. A search uses 1 credit per 10 results, rounded up, minimum 1.

notice
object

Present only when the request was changed to fit the plan. On the Free plan, k above 10 is capped to 10 results.