> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Image search

> Add Gateway-hosted image search to a request and read image citations, usage, and pricing.

Image search lets a model find images on the web during a request. Gateway runs the search with Parallel and returns image URLs, titles, and source pages to the model. For text results, use [web search](/merge-gateway/capabilities/web-search).

## Send a request with image search

Add `{"type": "merge:image_search"}` to `tools`. The model decides when to search, and each search can include up to three queries. Results are passed to the model as untrusted data.

**`cURL`**

```bash title="cURL"
curl https://api-gateway.merge.dev/v1/responses \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "input": [
      {"type": "message", "role": "user", "content": "Show me photos of the Golden Gate Bridge at sunrise."}
    ],
    "tools": [
      {"type": "merge:image_search", "parameters": {"mode": "fast", "max_results": 5}}
    ]
  }'
```

**`Python`**

```python title="Python"
# pip install merge-gateway-python
import os
from merge_gateway import MergeGateway

client = MergeGateway(api_key=os.environ["MERGE_GATEWAY_API_KEY"])

response = client.responses.create(
    model="anthropic/claude-sonnet-4-6",
    input=[{"type": "message", "role": "user", "content": "Show me photos of the Golden Gate Bridge at sunrise."}],
    tools=[{"type": "merge:image_search", "parameters": {"mode": "fast", "max_results": 5}}],
)
print(response.output[0].content[0].text)
```

It also works on the OpenAI- and Anthropic-compatible endpoints. On Anthropic Messages, `name` is optional:

**`cURL (Anthropic Messages)`**

```bash title="cURL (Anthropic Messages)"
curl https://api-gateway.merge.dev/v1/anthropic/v1/messages \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Find a diagram of the water cycle."}],
    "tools": [{"type": "merge:image_search"}]
  }'
```

## Parameters

Set these in the tool's `parameters` object.

| Parameter          | Default | Description                                                                                                       |
| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `mode`             | `fast`  | `fast` or `advanced`. `advanced` costs more per search                                                            |
| `max_results`      | `10`    | Images per search, 1 to 20                                                                                        |
| `max_search_calls` | `3`     | Searches the model can run in one request, 1 to 10. Past it the model gets a tool error instead of another search |
| `user_location`    | None    | Only `country` is used, to bias results                                                                           |

## Read citations and usage

Each image the model uses comes back as a `url_citation` annotation. `url` is the source page and `image_url` is the image. `width` and `height` are included when known. A citation is only added when the answer text contains the image or page URL.

```json
{
  "type": "text",
  "text": "Here is one: https://example.com/images/bridge.jpg",
  "annotations": [
    {
      "type": "url_citation",
      "url": "https://example.com/golden-gate",
      "title": "Golden Gate Bridge at sunrise",
      "image_url": "https://example.com/images/bridge.jpg",
      "width": 1600,
      "height": 900
    }
  ]
}
```

Search counts appear in:

* `usage.server_tool_use.image_search_requests` counts searches, fast and advanced together.
* OpenAI-compatible responses add `tool_usage.image_search.num_requests`.

## Combine with web search

Add both tools to the same request:

```json
"tools": [
  {"type": "merge:web_search"},
  {"type": "merge:image_search", "parameters": {"max_results": 5}}
]
```

Each tool has its own parameters and is billed separately.

## Pricing

Image search is billed per search, separately from tokens. Your organization's standard margin applies.

| Mode       | Price per search |
| ---------- | ---------------- |
| `fast`     | \$0.001          |
| `advanced` | \$0.005          |

Price doesn't depend on the number of images returned. Failed searches aren't billed.

## Limitations

* Not available in [batch inference](/merge-gateway/capabilities/batch-inference) or [Fusion](/merge-gateway/capabilities/fusion).
* Not available with [zero data retention](/merge-gateway/security/zero-data-retention). Requests from those organizations are rejected.
* Results are links to third-party images. Make sure you have the rights to use them.
* The model's search queries are checked against your organization's DLP policy before they're sent. A blocked query returns a tool error to the model and isn't billed.
* Only one image search tool per request.

## Errors

| Status | Code                             | Cause                                                    |
| ------ | -------------------------------- | -------------------------------------------------------- |
| `400`  | `image_search_unavailable`       | Image search isn't configured                            |
| `400`  | `server_tool_unavailable`        | Image search is temporarily disabled                     |
| `400`  | `invalid_image_search_mode`      | `mode` isn't `fast` or `advanced`                        |
| `400`  | `invalid_server_tool_parameters` | `parameters` isn't an object, or a value is out of range |
| `400`  | `server_tool_zdr_unavailable`    | Zero data retention is on                                |
| `400`  | `duplicate_server_tool`          | More than one image search tool                          |
| `400`  | `fusion_unsupported_tools`       | Sent with `model: "fusion"`                              |
| `422`  | `web_search_unsupported`         | Sent in a batch line                                     |

## Next steps

#### [Web search](/merge-gateway/capabilities/web-search)

Look up current web information with URL citations

#### [Tool calling](/merge-gateway/capabilities/tool-calling)

Define your own tools and return their results to the model

#### [Zero data retention](/merge-gateway/security/zero-data-retention)

Which Gateway features work with zero data retention