| name | unsplash-image |
| description | Search for images on Unsplash and download them. Optionally add text overlay (title/subtitle) to the image. Use when the user asks to find a stock photo, search for an image, get an Unsplash image, or download a photo with text. |
| argument-hint | ["search query"] |
| allowed-tools | Bash(*), Read, Write |
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 (contains UNSPLASH_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.full or urls.raw.
