How do I install the Unsplash Image skill?

Run npx skillmds add openclaudia/unsplash-image in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Unsplash Image safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Unsplash Image?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Unsplash Image free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Unsplash Image?

openclaudia (@openclaudia) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Unsplash Image by openclaudia — Agent Skill

Name: Unsplash Image
Rating: 4.666666666666667 (3 reviews)
Author: openclaudia

Unsplash Image

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.

openclaudia 2e79502 3.1 KB Updated Sep 9, 2026

File contents

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.

---name: unsplash-imagedescription: 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.--- # 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 ```bash python ~/.agents/tools/unsplash-search.py \ --query "nature landscape" \ --output ./image.jpg ``` ### With orientation filter ```bash python ~/.agents/tools/unsplash-search.py \ --query "coffee shop" \ --orientation landscape \ --output ./coffee.jpg ``` ### With text overlay (title and subtitle) ```bash 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 ```bash python ~/.agents/tools/unsplash-search.py \ --query "sunset" \ --list ``` ### Pick the first result instead of random ```bash 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: ```bash 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`.

Frequently asked questions