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 up to five image results; use SearchResultMode.FULL for the untouched response
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

Compact mode returns up to five images_results. Items can include title, original image URL, thumbnail, source page, dimensions, source name, and position. Your application should not assume every result contains every optional field.

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.