Image Well
Search and download images from 12 sources through a single CLI. Four sources work with zero API keys (Openverse, Wikimedia, Met Museum, NASA). Additional sources activate when keys are set.
Quick Start
# Search across all no-key sources
uv run ~/.claude/skills/image-well/scripts/well.py search "ancient Minoan fresco"
# Use a preset for domain-specific searches
uv run ~/.claude/skills/image-well/scripts/well.py search "F-35 fighter jet" --preset military
# Download results with metadata sidecars
uv run ~/.claude/skills/image-well/scripts/well.py search "sunset" --format download --output ./images/
# Check which sources are available
uv run ~/.claude/skills/image-well/scripts/well.py sources
# Visual HTML preview — opens in browser, no context pollution
uv run ~/.claude/skills/image-well/scripts/well.py search "bronze statue" --format html
# Output as JSON for piping
uv run ~/.claude/skills/image-well/scripts/well.py search "cat" --format json
Sources
| Tier |
Source |
Key Required |
License |
| 1 |
Openverse (800M+) |
No |
CC variants |
| 1 |
Wikimedia Commons |
No |
CC variants |
| 1 |
Met Museum (375k) |
No |
CC0 |
| 1 |
NASA (140k) |
No |
Public Domain |
| 2 |
Pexels |
PEXELS_API_KEY |
Pexels License |
| 2 |
Pixabay |
PIXABAY_API_KEY |
Pixabay License |
| 2 |
Rijksmuseum (700k) |
RIJKSMUSEUM_API_KEY |
CC0 |
| 2 |
Unsplash |
UNSPLASH_ACCESS_KEY |
Unsplash License |
| 3 |
Smithsonian |
No |
CC0 |
| 3 |
Europeana (50M+) |
EUROPEANA_API_KEY |
Mixed |
| 3 |
Iconify (275k icons) |
No |
Various |
| 3 |
Pollinations AI |
No |
Free Use (AI gen) |
Add Tier 2 keys to ~/.config/env/secrets.env for expanded coverage.
Presets
| Preset |
Sources |
Use Case |
military |
nasa, wikimedia, smithsonian |
Defense/military imagery |
museum |
met, rijksmuseum, smithsonian |
Art, antiquities, historical |
texture |
wikimedia, pollinations |
Game dev, 3D materials |
stock |
pexels, pixabay, unsplash |
Editorial photography |
all-free |
openverse, wikimedia, met, nasa, smithsonian |
All no-key sources |
Options
--sources NAME [...] Specific sources to search
--preset NAME Use a preset group
--limit N Max results per source (default: 10)
--license LICENSE Filter: cc0, cc-by, cc-by-sa, any
--format FORMAT table, json, download, urls, html, tunnel
--output DIR Download directory (default: ./well-images/)
--no-cache Skip result cache
--timeout N Per-source timeout in seconds (default: 15)
--quiet Suppress progress output
Workflows
Source images for a project
# Search, review in table, then download the good ones
uv run well.py search "Mediterranean landscape" --preset stock --format json > results.json
# Review results.json, then download specific URLs
Build an image corpus
# Download CC0 images for a research project
uv run well.py search "Bronze Age pottery" --preset museum --license cc0 --format download --output ./corpus/
Pipe to image-forge for processing
# Search, download, then resize with image-forge
uv run well.py search "sunset" --format download --output ./raw/
# Then use image-forge skill to process downloaded images
Cache
Results are cached for 24 hours at ~/.cache/image-well/.
uv run well.py cache stats # Show cache size
uv run well.py cache clear # Clear all cached results
1---2name: image-well3description: Search and download images from 12 APIs in parallel (Openverse, Pexels, Pixabay, Met Museum, NASA, Rijksmuseum, Wikimedia Commons, Unsplash, Smithsonian, Europeana, Iconify, Pollinations AI). Supports license filtering, presets (military, museum, stock), cached results, and bulk download with metadata sidecars. Triggers on find images, stock photos, public domain artwork, museum images, CC-licensed, NASA photos, icons.4---5
6# Image Well
7
8Search and download images from 12 sources through a single CLI. Four sources work with zero API keys (Openverse, Wikimedia, Met Museum, NASA). Additional sources activate when keys are set.
9
10## Quick Start
11
12```bash
13# Search across all no-key sources
14uv run ~/.claude/skills/image-well/scripts/well.py search "ancient Minoan fresco"
15
16# Use a preset for domain-specific searches
17uv run ~/.claude/skills/image-well/scripts/well.py search "F-35 fighter jet" --preset military
18
19# Download results with metadata sidecars
20uv run ~/.claude/skills/image-well/scripts/well.py search "sunset" --format download --output ./images/
21
22# Check which sources are available
23uv run ~/.claude/skills/image-well/scripts/well.py sources
24
25# Visual HTML preview — opens in browser, no context pollution
26uv run ~/.claude/skills/image-well/scripts/well.py search "bronze statue" --format html
27
28# Output as JSON for piping
29uv run ~/.claude/skills/image-well/scripts/well.py search "cat" --format json
30```
31
32## Sources
33
34| Tier | Source | Key Required | License |
35|------|--------|-------------|---------|
36| 1 | Openverse (800M+) | No | CC variants |
37| 1 | Wikimedia Commons | No | CC variants |
38| 1 | Met Museum (375k) | No | CC0 |
39| 1 | NASA (140k) | No | Public Domain |
40| 2 | Pexels | `PEXELS_API_KEY` | Pexels License |
41| 2 | Pixabay | `PIXABAY_API_KEY` | Pixabay License |
42| 2 | Rijksmuseum (700k) | `RIJKSMUSEUM_API_KEY` | CC0 |
43| 2 | Unsplash | `UNSPLASH_ACCESS_KEY` | Unsplash License |
44| 3 | Smithsonian | No | CC0 |
45| 3 | Europeana (50M+) | `EUROPEANA_API_KEY` | Mixed |
46| 3 | Iconify (275k icons) | No | Various |
47| 3 | Pollinations AI | No | Free Use (AI gen) |
48
49Add Tier 2 keys to `~/.config/env/secrets.env` for expanded coverage.
50
51## Presets
52
53| Preset | Sources | Use Case |
54|--------|---------|----------|
55| `military` | nasa, wikimedia, smithsonian | Defense/military imagery |
56| `museum` | met, rijksmuseum, smithsonian | Art, antiquities, historical |
57| `texture` | wikimedia, pollinations | Game dev, 3D materials |
58| `stock` | pexels, pixabay, unsplash | Editorial photography |
59| `all-free` | openverse, wikimedia, met, nasa, smithsonian | All no-key sources |
60
61## Options
62
63```
64--sources NAME [...] Specific sources to search
65--preset NAME Use a preset group
66--limit N Max results per source (default: 10)
67--license LICENSE Filter: cc0, cc-by, cc-by-sa, any
68--format FORMAT table, json, download, urls, html, tunnel
69--output DIR Download directory (default: ./well-images/)
70--no-cache Skip result cache
71--timeout N Per-source timeout in seconds (default: 15)
72--quiet Suppress progress output
73```
74
75## Workflows
76
77### Source images for a project
78```bash
79# Search, review in table, then download the good ones
80uv run well.py search "Mediterranean landscape" --preset stock --format json > results.json
81# Review results.json, then download specific URLs
82```
83
84### Build an image corpus
85```bash
86# Download CC0 images for a research project
87uv run well.py search "Bronze Age pottery" --preset museum --license cc0 --format download --output ./corpus/
88```
89
90### Pipe to image-forge for processing
91```bash
92# Search, download, then resize with image-forge
93uv run well.py search "sunset" --format download --output ./raw/
94# Then use image-forge skill to process downloaded images
95```
96
97## Cache
98
99Results are cached for 24 hours at `~/.cache/image-well/`.
100
101```bash
102uv run well.py cache stats # Show cache size
103uv run well.py cache clear # Clear all cached results
104```
majiayu000