> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Search

> Search for web images from the Agent API with result limits, domain and format filters, typed results, streaming events, and per-invocation pricing.

## 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.

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript Typescript theme={null}
  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);
    }
  }
  ```

  ```bash cURL theme={null}
  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
  ```
</CodeGroup>

## 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). |

## 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

<Warning>
  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.
</Warning>

### 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"]`.

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript Typescript theme={null}
  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);
  ```

  ```bash cURL theme={null}
  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
  ```
</CodeGroup>

## Response shape

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

```json theme={null}
{
  "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](/docs/getting-started/pricing) page for full details.

## Next steps

<CardGroup cols={2}>
  <Card title="Web Search" icon="world-search" href="/docs/agent-api/tools/web-search">
    Search the live web for source-grounded text results.
  </Card>

  <Card title="Image attachments" icon="image" href="/docs/agent-api/image-attachments">
    Send an image as input for the model to analyze.
  </Card>

  <Card title="Migrate from Sonar" icon="arrow-right-arrow-left" href="/docs/agent-api/migrate-from-sonar/how-to#sonar-specific-parameters">
    Map Sonar image-result parameters to the Image Search tool.
  </Card>

  <Card title="API Reference" icon="code-circle" href="/api-reference/agent-post">
    View the complete Agent API request and response schemas.
  </Card>
</CardGroup>