Unsplash Image Search & Download

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

--query, -q

--output, -o

--orientation

landscape

portrait

squarish

--color

blue

green

red

black_and_white

--pick

random

first

--title

--subtitle

--list

--count

Text Overlay

--title

• Semi-transparent dark background behind the text
• White title text with shadow
• Gray subtitle text (if provided)
• Automatic word wrapping and font sizing

pip install Pillow

Dependencies

• requests

  (for API calls and image download)

• Pillow

  (only needed if using text overlay with

  --title

  )

pip install requests Pillow

Output

• 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

  .