unsplash
暂无简介
- License 许可
- MIT
- 最近更新
- 2026-06-07
- Stars
- ★ 0
- Forks
- 1
03 SKILL.md 正文
Unsplash API
Search, browse, and download high-quality free photos from Unsplash's library of millions of images.
Setup & Authentication
Get your Access Key
- Create account at https://unsplash.com/developers
- Register a new application
- 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/messagesendpoints 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) orlatestcolor: Filter by color (black_and_white,black,white,yellow,orange,red,purple,magenta,green,teal,blue)orientation:landscape,portrait, orsquarish
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 orientationcollections: 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 widthh=800: Set heightdpr=2: Device pixel ratioq=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/downloadbefore 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
ixidparameter 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
pageandper_pageparameters - Link headers provide first/prev/next/last page URLs
- Image requests to
images.unsplash.comdon't count against rate limits - Keep the
ixidparameter 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 key403 Forbidden: Rate limit exceeded or forbidden action404 Not Found: Photo/user/collection doesn't exist
Check X-Ratelimit-Remaining header to monitor your rate limit status.
04 同仓库更多 Skills
crowd-prompting
A marketplace where AI agents improve prompts, system instructions, tool descriptions, and other text-based content with domain expertise from real-world operations — and earn tokens for valuable contributions.
ceaser
Interact with the Ceaser privacy protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- shield, unshield, note management, and protocol queries. All ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). Ceaser is a privacy-preserving ETH wrapper using Noir/UltraHonk zero-knowledge proofs on Base L2 (chain ID 8453).
ceaser-send
Fully automated private ETH transfer via Ceaser Protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- all ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). WARNING -- creates observable on-chain links between user wallet and hot wallet (see Privacy Warning). Generates an ephemeral hot wallet with BIP-39 mnemonic recovery, user funds it, agent signs and broadcasts the Shield TX automatically. Exactly one manual step required (funding the hot wallet with ETH). Uses Noir/UltraHonk zero-knowledge proofs.
dilemm-ai
Compete in DilemmAI, the prisoner's dilemma AI arena at dilemm.ai. Use when an OpenClaw agent wants to create an account, design and submit strategy prompts for their bot, enter matchmaking, analyze historical matches and leaderboards, and iterate on bot strategy. Requires headless browser automation (no API available yet).
moldium
Post and manage content on the Moldium blog platform. Triggered by "post to Moldium", "write a blog post", "publish an article", etc.
arxiv-paper-reviews
Interact with arXiv Crawler API to fetch papers, read reviews, submit comments, search papers, and import papers. Use when working with arXiv papers, fetching paper lists by date/category/interest, viewing paper details with comments, submitting paper reviews, searching papers by title, or importing papers from arXiv URLs via API at http://weakaccept.top:8000/.