Skip to main content
POST
/
image-search
curl --request POST \
  --url https://api.octen.ai/image-search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inputs": [
    {
      "type": "text",
      "data": "Preview deployments card with dark theme"
    }
  ],
  "topic": "design",
  "count": 3,
  "include_domains": [
    "unkey.dev",
    "stripe.com",
    "linear.app"
  ],
  "html_snippet": {
    "enable": true,
    "max_tokens": 5000
  }
}
'
{
  "request_id": "req_9d1c4f7a2e6b0853",
  "data": {
    "results": [
      {
        "title": "Scandinavian Minimalist Living Room",
        "url": "https://images.unsplash.com/photo-scandi-living-room.jpg",
        "source_page": "https://unsplash.com/photos/scandi-living-room",
        "description": "A Scandinavian minimalist living room with light wood flooring, an off-white sofa, and greenery; the composition is very close to the uploaded image.",
        "width": 1920,
        "height": 1280,
        "thumbnail": "https://images.unsplash.com/photo-scandi-living-room.jpg?w=200",
        "time_published": "2024-08-21T17:10:00+00:00",
        "time_last_crawled": "2026-06-08T11:55:42+08:00"
      },
      {
        "title": "Minimalist Interior Inspiration",
        "url": "https://i.pinimg.com/originals/minimal-interior.jpg",
        "source_page": "https://www.pinterest.com/pin/minimal-interior-inspiration",
        "description": "Minimalist interior design inspiration; the palette and layout are close to the uploaded image.",
        "width": 736,
        "height": 981,
        "thumbnail": "https://i.pinimg.com/236x/minimal-interior.jpg"
      }
    ]
  },
  "meta": {
    "usage": {
      "num_search_queries": 1
    },
    "latency": 642
  }
}

Authorizations

​
Authorization
string
header
required

Bearer token used for request authentication. Alternatively, you can send the API key in the x-api-key header. Note: A payment method is required to use the API.

Body

application/json

Request body for the Image Search API.

​
inputs
object[]
required

Multimodal input array. Currently only a single input is supported: either one text input or one image input.

Required array length: 1 element
​
topic
enum<string>
default:general

Use general for general image search, or design for design reference.

Available options:
general,
design
​
count
integer
default:5

Number of results to return.

Required range: 1 <= x <= 10
​
include_domains
string[]

Domains to include, matched against each result's source_page URL.

​
exclude_domains
string[]

Domains to exclude, matched against each result's source_page URL.

​
time_range
enum<string>

Relative time window counting back from the current time, filtered by publish time. Mutually exclusive with start_time/end_time — if both are provided, start_time/end_time take precedence.

Available options:
day,
week,
month,
year,
d,
w,
m,
y
​
start_time
string<date-time>

Start time for filtering results by publish time. ISO 8601 format.

Example:

"2025-01-01T00:00:00+08:00"

​
end_time
string<date-time>

End time for filtering results by publish time. ISO 8601 format.

Example:

"2025-01-01T00:00:00+08:00"

​
safesearch
enum<string>
default:strict

Controls filtering of explicit/adult content. off disables filtering; strict drops all adult content.

Available options:
off,
strict
​
html_snippet
object

Only effective when topic=design; controls whether an html_snippet is returned for each result.

Response

Successful image search response

​
request_id
string

The unique identifier for this request.

​
data
object

The main response payload.

​
meta
object

Additional metadata for the Image Search request.