Skill

unsplash-image

Searches Unsplash for images, downloads them, and adds optional title/subtitle text overlays. Useful for stock photos, image searches, or generating titled visuals.

Python

Bash

cli-tools

design

Install

npx claudepluginhub joshuarweaver/cascade-communication --plugin openclaudia-openclaudia-skills

Tool Access

This skill is limited to using the following tools:

Bash(*)ReadWrite

Preview

Search Unsplash for images, download them, and optionally add text overlay.

SKILL.md

Similar Skills

using-git-worktrees

Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.

superpowers

168.3k

subagent-driven-development

3 files

Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.

superpowers

168.3k

dispatching-parallel-agents

Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.

superpowers

168.3k

Stats

Stars401

Forks5

Last CommitApr 10, 2026

Actions

View Source View Plugin View on GitHub View README

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.