OpenSkillIndex← back to search
claude-code

Skills unsplash

Unsplash API

install
source · Clone the upstream repo
git clone https://github.com/openclaw/skills
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/brokenwatch24/unsplash" ~/.claude/skills/clawdbot-skills-unsplash && rm -rf "$T"
manifest: skills/brokenwatch24/unsplash/SKILL.md
source content

Unsplash API

Search, browse, and download high-quality free photos from Unsplash's library of millions of images.

Setup & Authentication

Get your Access Key

  1. Create account at https://unsplash.com/developers
  2. Register a new application
  3. Copy your Access Key (starts with your app name)

Store credentials

mkdir -p ~/.config/unsplash
echo "YOUR_ACCESS_KEY" > ~/.config/unsplash/access_key
chmod 600 ~/.config/unsplash/access_key

Or set environment variable:

export UNSPLASH_ACCESS_KEY="your_access_key_here"

Rate Limits

  • Demo: 50 requests/hour
  • Production: 5,000 requests/hour (after app approval)
  • Only 
    /v1/messages
    endpoints count; image URLs (
    images.unsplash.com
    ) don't

Common Operations

Search Photos

curl "https://api.unsplash.com/search/photos?query=nature&per_page=10" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

Parameters:

  • query
    : Search terms (required)
  • page
    : Page number (default: 1)
  • per_page
    : Results per page (default: 10, max: 30)
  • order_by
    : 
    relevant
    (default) or 
    latest
  • color
    : Filter by color (
    black_and_white
    , 
    black
    , 
    white
    , 
    yellow
    , 
    orange
    , 
    red
    , 
    purple
    , 
    magenta
    , 
    green
    , 
    teal
    , 
    blue
    )
  • orientation
    : 
    landscape
    , 
    portrait
    , or 
    squarish

Get Random Photo

curl "https://api.unsplash.com/photos/random?query=coffee&count=1" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

Parameters:

  • query
    : Limit to search term (optional)
  • count
    : Number of photos (1-30, default: 1)
  • orientation
    : Filter by orientation
  • collections
    : Filter by collection IDs (comma-separated)

Get Photo Details

curl "https://api.unsplash.com/photos/PHOTO_ID" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

Returns full photo metadata including EXIF, location, user info, and all image URLs.

Track Download (Required!)

Important: You MUST trigger this endpoint when downloading a photo to comply with API guidelines.

curl "https://api.unsplash.com/photos/PHOTO_ID/download" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

This increments the download counter. Response includes the download URL.

List Editorial Feed

curl "https://api.unsplash.com/photos?per_page=10" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

Browse Collections

# List all collections
curl "https://api.unsplash.com/collections?per_page=10" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

# Get collection photos
curl "https://api.unsplash.com/collections/COLLECTION_ID/photos" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

User Photos

curl "https://api.unsplash.com/users/USERNAME/photos?per_page=10" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

Working with Images

Image URLs

Every photo response includes these URLs:

{
  "urls": {
    "raw": "https://images.unsplash.com/photo-xxx?ixid=xxx",
    "full": "...?ixid=xxx&q=80&fm=jpg",
    "regular": "...?ixid=xxx&w=1080&fit=max",
    "small": "...?w=400&fit=max",
    "thumb": "...?w=200&fit=max"
  }
}

Dynamic Resizing

Add parameters to any image URL (keep the 

ixid
parameter!):

  • w=1500
    : Set width
  • h=800
    : Set height
  • dpr=2
    : Device pixel ratio
  • q=75
    : Quality (1-100)
  • fm=jpg
    : Format (jpg, png, webp, avif)
  • fit=crop
    : Fit mode (crop, max, clip)
  • crop=entropy
    : Crop mode

Example:

https://images.unsplash.com/photo-xxx?ixid=xxx&w=1500&h=1000&fit=crop&q=85

BlurHash Placeholders

Each photo includes a 

blur_hash
field - a compact string representation for showing blurred placeholders while images load.

{
  "blur_hash": "LoC%a7IoIVxZ_NM|M{s:%hRjWAo0"
}

Response Structure

Photo Object (abbreviated)

{
  "id": "LBI7cgq3pbM",
  "created_at": "2016-05-03T11:00:28-04:00",
  "width": 5245,
  "height": 3497,
  "color": "#60544D",
  "blur_hash": "LoC%a7IoIVxZ_NM|M{s:%hRjWAo0",
  "description": "A man drinking coffee",
  "urls": { "raw": "...", "full": "...", "regular": "..." },
  "links": {
    "download": "...",
    "download_location": "https://api.unsplash.com/photos/xxx/download"
  },
  "user": {
    "username": "johndoe",
    "name": "John Doe",
    "profile_image": { "small": "...", "medium": "...", "large": "..." }
  }
}

Search Response

{
  "total": 133,
  "total_pages": 7,
  "results": [ /* array of photo objects */ ]
}

Best Practices

Attribution

Always attribute photos to their creators:

Photo by [Name] on Unsplash

Link to photographer's Unsplash profile when possible.

Download Tracking

  • Call 
    /photos/:id/download
    before allowing users to download
  • This is required by Unsplash API Guidelines
  • Don't use it for just displaying images (that's tracked automatically via hotlinking)

Hotlinking

  • You can hotlink images directly from 
    images.unsplash.com
  • These don't count against rate limits
  • Views are tracked automatically
  • Always keep the 
    ixid
    parameter in URLs

Caching

  • Public endpoints (search, photos) are cacheable
  • Consider caching search results client-side to reduce API calls

Quick Reference

# Store key
export UNSPLASH_ACCESS_KEY="your_key"

# Search
curl "https://api.unsplash.com/search/photos?query=ocean&per_page=5" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

# Random photo
curl "https://api.unsplash.com/photos/random?query=mountains" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

# Get photo
curl "https://api.unsplash.com/photos/PHOTO_ID" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

# Track download (required when downloading!)
curl "https://api.unsplash.com/photos/PHOTO_ID/download" \
  -H "Authorization: Client-ID ${UNSPLASH_ACCESS_KEY}"

Notes

  • Base URL: 
    https://api.unsplash.com
  • All responses are JSON
  • Pagination via 
    page
    and 
    per_page
    parameters
  • Link headers provide first/prev/next/last page URLs
  • Image requests to 
    images.unsplash.com
    don't count against rate limits
  • Keep the 
    ixid
    parameter when using/manipulating image URLs
  • For production use, apply for increased rate limits in your dashboard

Common Filters

Colors

black_and_white
, 
black
, 
white
, 
yellow
, 
orange
, 
red
, 
purple
, 
magenta
, 
green
, 
teal
, 
blue

Orientations

landscape
, 
portrait
, 
squarish

Sort Options

  • Photos: 
    latest
    , 
    oldest
    , 
    popular
  • Search: 
    relevant
    , 
    latest

Error Handling

  • 401 Unauthorized
    : Invalid or missing access key
  • 403 Forbidden
    : Rate limit exceeded or forbidden action
  • 404 Not Found
    : Photo/user/collection doesn't exist

Check 

X-Ratelimit-Remaining
header to monitor your rate limit status.