Skip to main content
POST
Image search

Authorizations

x-api-key
string
header
required

Body

application/json

Image search request.

search_queries
string[]
required

Concise keyword image search queries. At least one query is required, and at most 5, each at most 200 characters.

Maximum array length: 5
Maximum string length: 200
objective
string | null

Natural-language description of the images wanted. Used together with search_queries to focus results on the most relevant images. At most 5000 characters.

mode
enum<string> | null

fast: lowest latency and cost. advanced (default): slower, with higher-quality results.

Available options:
fast,
advanced
session_id
string | null

Session identifier that groups related calls made as part of a larger task. Echoed back in the response when nonempty; generated by the server if omitted, null, or empty.

Maximum string length: 1000
client_model
string | null

The model generating this request and consuming the results.

Example:

"claude-opus-4-7"

advanced_settings
AdvancedImageSearchSettings · object | null

Advanced configuration for location and result count.

Response

Successful Response

Image search response.

search_id
string
required

Search ID. Example: search_cad0a6d2dec046bd95ae900527d880e7

session_id
string
required

Session identifier, echoed back from the request when nonempty; otherwise generated by the server. Pass it to later calls made as part of the same task.

Example:

"session_8a911eb27c7a4afaa20d0d9dc98d07c0"

results
ImageSearchResult · object[]
required

A list of image results, ordered by decreasing relevance.

warnings
Warning · object[] | null

Warnings for the search request, if any.

usage
UsageItem · object[] | null

Usage metrics for the search request.