Unsplash Image Search & Download
Search Unsplash for images, download them, and optionally add text overlay.
Tool Location
- Script:
~/.agents/tools/unsplash-search.py - Env file:
~/.agents/tools/.env(containsUNSPLASH_CLIENT_ID)
Quick Usage
Search and download a random matching image
python ~/.agents/tools/unsplash-search.py \
--query "nature landscape" \
--output ./image.jpg
With orientation filter
python ~/.agents/tools/unsplash-search.py \
--query "coffee shop" \
--orientation landscape \
--output ./coffee.jpg
With text overlay (title and subtitle)
python ~/.agents/tools/unsplash-search.py \
--query "technology abstract" \
--output ./cover.png \
--title "My Blog Post Title" \
--subtitle "A short description"
List results without downloading
python ~/.agents/tools/unsplash-search.py \
--query "sunset" \
--list
Pick the first result instead of random
python ~/.agents/tools/unsplash-search.py \
--query "mountains" \
--pick first \
--output ./mountains.jpg
CLI Options
| Option | Description |
|---|---|
--query, -q | (Required) Search query string |
--output, -o | (Required unless --list) Output file path |
--orientation | Filter: landscape, portrait, or squarish |
--color | Color filter (e.g., blue, green, red, black_and_white) |
--pick | How to select from results: random (default) or first |
--title | Title text to overlay on the image |
--subtitle | Subtitle text to overlay (only used with --title) |
--list | List search results instead of downloading |
--count | Number of results to fetch, max 30 (default: 30) |
Text Overlay
When --title is provided, the script adds a text overlay to the bottom portion of the image with:
- Semi-transparent dark background behind the text
- White title text with shadow
- Gray subtitle text (if provided)
- Automatic word wrapping and font sizing
Requires Pillow: pip install Pillow
Dependencies
requests(for API calls and image download)Pillow(only needed if using text overlay with--title)
Install if needed:
pip install requests Pillow
Output
The script prints:
- The download URL
- Photographer attribution (required by Unsplash)
- The saved file path
- Confirmation of text overlay if applied
Notes
- Unsplash API guidelines require attribution. The script prints photographer info.
- The script triggers Unsplash's download tracking endpoint as required by their API terms.
- Images are downloaded at "regular" quality (1080px width). For higher resolution, modify the script to use
urls.fullorurls.raw.