---
title: "Image Search"
method: POST
path: "/image-search"
---

# Image Search

`POST /image-search`

## Request

- Base URL: `https://api.octen.ai`
- URL: `https://api.octen.ai/image-search`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Searches the web for images.

## Request body

- ImageSearchRequest: Request body for the Image Search API.
  - `inputs` ImageSearchInput[], required: Multimodal input array. Currently only a single input is supported: either one text input or one image input.
    - `type` 'text' | 'image', required: The input type. A single image must be at most 5MB and one of: JPEG, PNG, WEBP, BMP, TIFF, ICO, DIB, ICNS, SGI.
    - `url` string: Image input as a public URL. For an image input, provide either `url` or `data`, not both.
    - `data` string: When `type` is `text`: the query content, max 500 characters. When `type` is `image`: base64-encoded image data, at most 5MB after encoding.
  - `count` integer: Number of results to return.
  - `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.
  - `safesearch` 'off' | 'strict': Controls filtering of explicit/adult content. `off` disables filtering; `strict` drops all adult content.

## Response `200`

Successful image search response

- ImageSearchResponse
  - `code` integer: Business status code. 0 indicates success.
  - `msg` string: A message describing the result.
  - `request_id` string: The unique identifier for this request.
  - `data` ImageSearchData: The main response payload.
    - `results` ImageSearchResult[]: A list of image search results.
      - `title` string: The title of the image.
      - `url` string: The image URL.
      - `source_page` string: URL of the original page hosting the image.
      - `description` string: Server-generated text description of the image content.
      - `width` integer: Image width in pixels.
      - `height` integer: Image height in pixels.
      - `thumbnail` string: Thumbnail URL.
  - `meta` ImageSearchMeta: Additional metadata for the Image Search request.
    - `usage` ImageSearchUsage: Usage information for the Image Search request.
      - `num_search_queries` integer: Number of search queries executed.
    - `latency` number: Response time in milliseconds.
    - `warning` string, nullable: Warning message, if any.

## Other responses

- `400`: Missing parameter inputs — Returned when a required parameter is missing.
- `401`: Invalid API Key — Returned when the API key is missing or invalid.
- `403`: Insufficient balance in account — Returned when the account balance is insufficient to complete the request.
- `413`: Payload too large — Returned when the request payload exceeds the size limit.
- `415`: Unsupported media type — Returned when the input media format is not supported.
- `422`: Input unreadable or invalid — Returned when an input cannot be read or is otherwise invalid.
- `429`: Exceeding the rate limit — Returned when the request exceeds the configured rate limit.
- `500`: Internal error — Returned when an unexpected server-side error occurs.

---

[API](https://skmtc.dev/octen/apis/octen-api.md) - [All operations](https://skmtc.dev/octen/apis/octen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octen/apis/octen-api/revisions/aaa6caaf46b0?raw)