Skip to navigation

Image search

Let models find images on the web through Gateway

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.

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 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}}
]
}'

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

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.

ParameterDefaultDescription
modefastfast or advanced. advanced costs more per search
max_results10Images per search, 1 to 20
max_search_calls3Searches the model can run in one request, 1 to 10. Past it the model gets a tool error instead of another search
user_locationNoneOnly 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.

{
"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.

Add both tools to the same request:

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

ModePrice 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 or Fusion.
  • Not available with 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

StatusCodeCause
400image_search_unavailableImage search isn’t configured
400server_tool_unavailableImage search is temporarily disabled
400invalid_image_search_modemode isn’t fast or advanced
400invalid_server_tool_parametersparameters isn’t an object, or a value is out of range
400server_tool_zdr_unavailableZero data retention is on
400duplicate_server_toolMore than one image search tool
400fusion_unsupported_toolsSent with model: "fusion"
422web_search_unsupportedSent in a batch line

Next steps