---
name: image-search
description: Search for web images and optionally download selected images to local files. Use when the user asks to find pictures, reference images, product photos, visual inspiration, covers, illustrations from the web, or images to place into documents, slides, or reports.
---
# image-search

Use this skill when the user needs images from the web.

This skill is independent from OpenClaw's `web_search` provider configuration. Do not change Tavily, Brave, DuckDuckGo, or SearXNG settings to use this skill.

## Source Priority

Always prefer image sources in this order:

1. Pixabay
2. Pexels
3. Unsplash
4. Generic web image fallback

The script uses Pixabay/Pexels/Unsplash official APIs when the matching API key is configured. If no key is configured, it still searches those sources first through site-limited image search, then falls back to generic web image results.

Optional API key environment variables:

- `PIXABAY_API_KEY`
- `PEXELS_API_KEY`
- `UNSPLASH_ACCESS_KEY`

## Standard Workflow

1. Search for image candidates:

```bash
node ~/.openclaw/skills/image-search/scripts/search-images.mjs "<query>" --count 8
```

2. If the user needs usable local files, download a small number of selected results:

```bash
node ~/.openclaw/skills/image-search/scripts/search-images.mjs "<query>" --count 8 --download 3
```

3. Use the returned JSON:
   - `results[].imageUrl` is the original image URL.
   - `results[].thumbnailUrl` is the preview image.
   - `results[].sourcePageUrl` is the page where the image came from.
   - `results[].sourceProvider` shows whether the result came from `pixabay`, `pexels`, `unsplash`, or fallback search.
   - `results[].localPath` exists only when `--download` succeeds.

4. When using downloaded images in a PPT, Word file, report, or design task, use `localPath`.

## Output Rules

- Tell the user that web images may have copyright or usage restrictions unless they only need reference material.
- Prefer images with a clear `sourcePageUrl`.
- If downloads fail, still return image URLs and source pages when available.
- For user-facing answers, show the best 3-8 image candidates with title/source, not a raw wall of JSON.

## Examples

```bash
node ~/.openclaw/skills/image-search/scripts/search-images.mjs "现代酒店大堂 设计 参考图" --count 6 --download 2
node ~/.openclaw/skills/image-search/scripts/search-images.mjs "coffee shop menu board photo" --count 8
node ~/.openclaw/skills/image-search/scripts/search-images.mjs "AI enterprise dashboard hero illustration" --count 5 --download 1 --output ~/Desktop/image-search-results.json
```