Image search with images_search

images_search searches Google Images for image URLs and structured metadata. It is useful when the agent needs visual references rather than ordinary web pages.

When to use it

Use it for visual research, inspiration gathering, product imagery discovery, identifying visual themes, or locating source pages for images.

Choose web_search for text sources. This tool returns image metadata; it does not download, edit, license, or verify permission to reuse an image.

Quick example

from serpapi_search_tools import images_search

visual_search = images_search()
agent_tools = [visual_search]

Inputs the agent can provide

Field Type Required Meaning
query string yes The subject, object, style, or scene to search for

The engine is fixed to google_images, so the agent only needs to provide the image query.

Configure the tool

Constructor option Default Use it for
provider "auto" Detect the installed agent SDK
default_params None Fix safe search, locale, or other supported image filters
mode compact Return the main image result section; use SearchResultMode.FULL to keep supporting sections and all fields on retained results
response_format markdown Return Markdown by default, or use SearchResultFormat.JSON for structured fields
result_limit 50 Maximum images_results retained in either mode; use None for all returned images
api_key None Override environment key lookup
timeout None Set the built-in client timeout
client None Provide a custom client for logging, caching, or tests
include_examples True Add a sample image query to the description
name "images_search" Rename a specialized visual-search tool

Useful SerpApi parameters

Safe search is a common application-controlled policy:

from serpapi_search_tools import images_search

safe_images = images_search(
    default_params={"safe": "active", "hl": "en", "gl": "us"},
    name="safe_image_search",
)

Google Images supports additional size, color, type, rights, time, and page filters. Use the official reference for accepted values. The package rejects known conflicts such as location with uule, and relative-period filters with explicit start/end dates.

What comes back

Both modes return up to result_limit images_results (50 by default). Compact mode keeps the image URLs, thumbnails, source pages, dimensions, titles, and other useful result data while omitting supporting response sections and redundant navigation fields. Use result_limit=None to keep all returned images. Result fields are optional, so normalization should handle missing values.

Common mistakes

  • Treating a returned image URL as a reuse license. Check the source and rights.
  • Sending both location and uule.
  • Mixing relative-period and explicit date filters.
  • Opting into full image responses for a model when compact mode is enough.

Official SerpApi documentation

See the image discovery recipe and the Pydantic AI image example.