---
title: "Image search"
method: POST
path: "/v1/images/search"
tags: ["Image Search"]
---

# Image search

`POST /v1/images/search`

## Request

- Base URL: `https://api.parallel.ai`
- URL: `https://api.parallel.ai/v1/images/search`
- Auth: API key in header `x-api-key`

Searches the web for images.

## Request body

- ImageSearchRequest: Image search request.
  - `objective` string, nullable: Natural-language description of the images wanted. Used together with search_queries to focus results on the most relevant images. At most 5000 characters.
  - `search_queries` string[], required: Concise keyword image search queries. At least one query is required, and at most 5, each at most 200 characters.
  - `mode` 'fast' | 'advanced', nullable: `fast`: lowest latency and cost. `advanced` (default): slower, with higher-quality results.
  - `session_id` string, nullable: 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.
  - `client_model` string, nullable: The model generating this request and consuming the results.
  - `advanced_settings` AdvancedImageSearchSettings: Advanced image search configuration.
    - `location` string, nullable: ISO 3166-1 alpha-2 country code for geo-targeted image results.
    - `max_results` integer, nullable: Upper bound on the number of results to return. Defaults to 10 if not provided. Values above the mode's maximum are reduced to it, with a warning.

## Response `200`

Successful Response

- ImageSearchResponse: 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.
  - `results` ImageSearchResult[], required: A list of image results, ordered by decreasing relevance.
    - `title` string, required: Image title, alt text, or caption.
    - `image_url` string, required: Direct URL of the full-size image.
    - `source_page_url` string, required: URL of the page the image appears on, for attribution and context.
    - `width` integer, nullable: Image width in pixels, if known.
    - `height` integer, nullable: Image height in pixels, if known.
  - `warnings` Warning[], nullable: Warnings for the search request, if any.
    - `type` 'spec_validation_warning' | 'input_validation_warning' | 'warning', required: Type of warning. Note that adding new warning types is considered a backward-compatible change.
    - `message` string, required: Human-readable message.
    - `detail` object, nullable: Optional detail supporting the warning.
  - `usage` UsageItem[], nullable: Usage metrics for the search request.
    - `name` string, required: Name of the SKU.
    - `count` integer, required: Count of the SKU.

## Other responses

- `422`: Request validation error

## Changes

- **2026-10-16** `fc4858951ccf`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/parallel-web/apis/parallel-api/changes/v1/images/search/post.md)

---

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