# Unsplash Image

Search for images on Unsplash and download them.

- Repository: https://github.com/OpenClaudia/openclaudia-skills (724 stars)
- Category: Media
- License: MIT
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add OpenClaudia/openclaudia-skills --skill unsplash-image -g -a claude-code -y`
Codex: `npx skills add OpenClaudia/openclaudia-skills --skill unsplash-image -g -a codex -y`
Cursor: `npx skills add OpenClaudia/openclaudia-skills --skill unsplash-image -g -a cursor -y`
Gemini CLI: `npx skills add OpenClaudia/openclaudia-skills --skill unsplash-image -g -a gemini-cli -y`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

The rest: https://github.com/OpenClaudia/openclaudia-skills/blob/HEAD/skills/stock-images/SKILL.md