Unsplash Image Tool
Unsplash image

Search for images on Unsplash and download them. Optionally add text overlay (title/subtitle) to the image.
--- 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
Overview
Search Unsplash for images, download them, and optionally add text overlay.
What you get
The download URL
Photographer attribution (required by Unsplash)
The saved file path
Confirmation of text overlay if applied
Manual install (npx, ZIP)
Claude Code
npx skills add OpenClaudia/openclaudia-skills --skill unsplash-image -g -a claude-codeClaude Code (degit)
npx degit OpenClaudia/openclaudia-skills/skills/stock-images#main ~/.claude/skills/unsplash-imageClaude.ai / desktop
Codex, Cursor, other agents
Connects with Agent Alley MCP · agentalley.io/mcp
Files included
SKILL.md3.0 KB
Read SKILL.md here
SKILL.md
Show the full text110 lines
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.
| 1 | |
| 2 | name unsplash-image |
| 3 | 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. |
| 4 | argument-hint [search query] |
| 5 | allowed-tools Bash(*), Read, Write |
| 6 | |
| 7 | |
| 8 | # Unsplash Image Search & Download |
| 9 | |
| 10 | Search Unsplash for images, download them, and optionally add text overlay. |
| 11 | |
| 12 | ## Tool Location |
| 13 | |
| 14 | Script: `~/.agents/tools/unsplash-search.py` |
| 15 | Env file: `~/.agents/tools/.env` (contains `UNSPLASH_CLIENT_ID`) |
| 16 | |
| 17 | ## Quick Usage |
| 18 | |
| 19 | ### Search and download a random matching image |
| 20 | |
| 21 | |
| 22 | python ~/.agents/tools/unsplash-search.py \ |
| 23 | --query "nature landscape" \ |
| 24 | --output ./image.jpg |
| 25 | |
| 26 | |
| 27 | ### With orientation filter |
| 28 | |
| 29 | |
| 30 | python ~/.agents/tools/unsplash-search.py \ |
| 31 | --query "coffee shop" \ |
| 32 | --orientation landscape \ |
| 33 | --output ./coffee.jpg |
| 34 | |
| 35 | |
| 36 | ### With text overlay (title and subtitle) |
| 37 | |
| 38 | |
| 39 | python ~/.agents/tools/unsplash-search.py \ |
| 40 | --query "technology abstract" \ |
| 41 | --output ./cover.png \ |
| 42 | --title "My Blog Post Title" \ |
| 43 | --subtitle "A short description" |
| 44 | |
| 45 | |
| 46 | ### List results without downloading |
| 47 | |
| 48 | |
| 49 | python ~/.agents/tools/unsplash-search.py \ |
| 50 | --query "sunset" \ |
| 51 | --list |
| 52 | |
| 53 | |
| 54 | ### Pick the first result instead of random |
| 55 | |
| 56 | |
| 57 | python ~/.agents/tools/unsplash-search.py \ |
| 58 | --query "mountains" \ |
| 59 | --pick first \ |
| 60 | --output ./mountains.jpg |
| 61 | |
| 62 | |
| 63 | ## CLI Options |
| 64 | |
| 65 | | Option | Description | |
| 66 | |--------|-------------| |
| 67 | | `--query, -q` | **(Required)** Search query string | |
| 68 | | `--output, -o` | **(Required unless --list)** Output file path | |
| 69 | | `--orientation` | Filter: `landscape`, `portrait`, or `squarish` | |
| 70 | | `--color` | Color filter (e.g., `blue`, `green`, `red`, `black_and_white`) | |
| 71 | | `--pick` | How to select from results: `random` (default) or `first` | |
| 72 | | `--title` | Title text to overlay on the image | |
| 73 | | `--subtitle` | Subtitle text to overlay (only used with --title) | |
| 74 | | `--list` | List search results instead of downloading | |
| 75 | | `--count` | Number of results to fetch, max 30 (default: 30) | |
| 76 | |
| 77 | ## Text Overlay |
| 78 | |
| 79 | When `--title` is provided, the script adds a text overlay to the bottom portion of the image with: |
| 80 | Semi-transparent dark background behind the text |
| 81 | White title text with shadow |
| 82 | Gray subtitle text (if provided) |
| 83 | Automatic word wrapping and font sizing |
| 84 | |
| 85 | **Requires Pillow**: `pip install Pillow` |
| 86 | |
| 87 | ## Dependencies |
| 88 | |
| 89 | `requests` (for API calls and image download) |
| 90 | `Pillow` (only needed if using text overlay with `--title`) |
| 91 | |
| 92 | Install if needed: |
| 93 | |
| 94 | pip install requests Pillow |
| 95 | |
| 96 | |
| 97 | ## Output |
| 98 | |
| 99 | The script prints: |
| 100 | The download URL |
| 101 | Photographer attribution (required by Unsplash) |
| 102 | The saved file path |
| 103 | Confirmation of text overlay if applied |
| 104 | |
| 105 | ## Notes |
| 106 | |
| 107 | Unsplash API guidelines require attribution. The script prints photographer info. |
| 108 | The script triggers Unsplash's download tracking endpoint as required by their API terms. |
| 109 | Images are downloaded at "regular" quality (1080px width). For higher resolution, modify the script to use `urls.full` or `urls.raw`. |
| 110 |
Details
- License
- MIT
- Stars on the repo
- ★ 705
- Checked
- Source
- OpenClaudia/openclaudia-skills ↗
- Creator
- OpenClaudia · 78 listings
Similar skills
See all →
Cross-Platform Reverse Engineer
Brainstorm Ideas
Code Review Feedback Analyzer
Bug Diagnosis Framework
Implement Spec
PR Description WriterMore from OpenClaudia
A/B Testing Framework
Affiliate Marketing Program
Ahrefs API Manager
AI Citations Report Generator
B2B Lead Enricher
Backlink Health Checker