Image Search

Overview

The image_search tool lets the model search for existing photographs, diagrams, illustrations, and other images on the web during an Agent API request. Results are returned as structured image_search_results output items, separate from the assistant’s text.

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-6-luna",
    input="Find images of the Golden Gate Bridge at sunset.",
    tools=[{"type": "image_search"}],
)

for item in response.output:
    if item.type == "image_search_results":
        for image in item.results:
            print(image.image_url, image.origin_url)

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
  model: 'openai/gpt-6-luna',
  input: 'Find images of the Golden Gate Bridge at sunset.',
  tools: [{ type: 'image_search' }],
});

for (const item of response.output) {
  if (item.type !== 'image_search_results') continue;
  for (const image of item.results) {
    console.log(image.image_url, image.origin_url);
  }
}

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-luna",
    "input": "Find images of the Golden Gate Bridge at sunset.",
    "tools": [{"type": "image_search"}]
  }' | jq

Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Must be `"image_search"`.
`max_results`	integer	No	Maximum number of images returned per call, from 1 to 30. Defaults to 5.
`filters`	object	No	Domain, format, and safe-search filters. See Filters.

Filters

Use filters to constrain the image sources and formats used by image_search.

Filter	Type	Description
`domain_filter`	array of strings	Include or exclude up to 10 domains. Prefix entries with `-` to exclude them.
`format_filter`	array of strings	Include up to 10 formats. Supported values are `bmp`, `gif`, `jpeg`, `png`, `webp`, and `svg`.
`safe_search`	boolean	Enable safe-search filtering. Defaults to `true`.

Domain filter

Use domain_filter in either allowlist mode or denylist mode, not both. For example, ["nasa.gov", "wikimedia.org"] includes only those domains, while ["-gettyimages.com", "-shutterstock.com"] excludes those domains.

Format filter

Use format_filter to return only the listed image formats, such as ["jpeg", "png"].

Filter example

This example allowlists NASA and Wikimedia, restricts results to JPEG and PNG images, and keeps safe search enabled. To use denylist mode instead, replace domain_filter with ["-gettyimages.com", "-shutterstock.com"].

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-6-luna",
    input="Find images of the Pillars of Creation.",
    tools=[
        {
            "type": "image_search",
            "filters": {
                "domain_filter": ["nasa.gov", "wikimedia.org"],
                "format_filter": ["jpeg", "png"],
                "safe_search": True,
            },
        }
    ],
)

print(response.output)

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const response = await client.responses.create({
  model: 'openai/gpt-6-luna',
  input: 'Find images of the Pillars of Creation.',
  tools: [
    {
      type: 'image_search',
      filters: {
        domain_filter: ['nasa.gov', 'wikimedia.org'],
        format_filter: ['jpeg', 'png'],
        safe_search: true,
      },
    },
  ],
});

console.log(response.output);

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-luna",
    "input": "Find images of the Pillars of Creation.",
    "tools": [
      {
        "type": "image_search",
        "filters": {
          "domain_filter": ["nasa.gov", "wikimedia.org"],
          "format_filter": ["jpeg", "png"],
          "safe_search": true
        }
      }
    ]
  }' | jq

Response shape

When the tool runs, output includes an image_search_results item before the final assistant message.

{
  "type": "image_search_results",
  "queries": ["Golden Gate Bridge sunset"],
  "results": [
    {
      "image_url": "https://images.example.com/golden-gate-sunset.jpg",
      "origin_url": "https://example.com/golden-gate-bridge",
      "width": 1920,
      "height": 1080,
      "title": "Golden Gate Bridge at sunset"
    }
  ]
}

Field	Type	Description
`type`	string	Always `"image_search_results"`.
`queries`	array of strings	Search queries generated by the model. May be omitted.
`results`	array	Image results. The array is empty when the search succeeds without matches.
`results[].image_url`	string	URL of the image.
`results[].origin_url`	string	URL of the page where the image was found.
`results[].width`	integer	Image width in pixels.
`results[].height`	integer	Image height in pixels.
`results[].title`	string	Optional image title or description.
`error`	string	Present as `"image_search_failed"` when the search fails. Failed calls return an empty `results` array and are not billed.

Streaming events

With stream: true, image search emits two typed reasoning events. Match them by call_id:

Event	Key fields	When it appears
`response.reasoning.image_search_queries`	`call_id`, `queries`, `sequence_number`, optional `thought`	When image search starts.
`response.reasoning.image_search_results`	`call_id`, `results`, `sequence_number`, optional `thought` and `usage`	When image results arrive.

The completed response also includes the image_search_results output item shown above.

Pricing

Each invocation of the image_search tool is billed at $2.50 per 1,000 tool invocations. See the Pricing page for full details.

Next steps

Web Search

Search the live web for source-grounded text results.

Image attachments

Send an image as input for the model to analyze.

Migrate from Sonar

Map Sonar image-result parameters to the Image Search tool.

API Reference

View the complete Agent API request and response schemas.

Getting Started

Router API

Agent API

Search API

Search SDK

Embeddings API

Decisions API

Perplexity SDK

Admin & Management

Resources

Overview

Parameters

Filters

Domain filter

Format filter

Filter example

Response shape

Streaming events

Pricing

Next steps

Web Search

Image attachments

Migrate from Sonar

API Reference

​Overview

​Parameters

​Filters

​Domain filter

​Format filter

​Filter example

​Response shape

​Streaming events

​Pricing

​Next steps

Web Search

Image attachments

Migrate from Sonar

API Reference

Overview

Parameters

Filters

Domain filter

Format filter

Filter example

Response shape

Streaming events

Pricing

Next steps