Back to Details

unsplash

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Unsplash Photo Search

Unsplash 图片搜索

Search and fetch high-quality photos from Unsplash with automatic attribution.
从Unsplash搜索并获取高质量图片，支持自动生成署名。

Quick Start

快速开始

bash
undefined
bash
undefined

Search for photos

搜索图片

./scripts/search.sh "sunset beach"
./scripts/search.sh "sunset beach"

Get random photos

获取随机图片

./scripts/random.sh "nature" 3
./scripts/random.sh "nature" 3

Track download (when user downloads)

跟踪下载（当用户下载图片时调用）

./scripts/track.sh PHOTO_ID
undefined
./scripts/track.sh PHOTO_ID
undefined

Setup (Interactive)

交互式设置

IMPORTANT: If the script returns 
UNSPLASH_ACCESS_KEY not set
, handle it interactively:
  1. Ask the user: "I need an Unsplash API key to search for photos. You can get a free key at https://unsplash.com/developers - do you have one?"
  2. Wait for the user to provide their key
  3. Save the key to 
    .env
    in the project root:
    bash
    echo "UNSPLASH_ACCESS_KEY=<user_provided_key>" >> .env
  4. Re-run the original search/random command
The skill automatically loads 
.env
from the project root on each run.
重要提示： 如果脚本返回
UNSPLASH_ACCESS_KEY not set
，请按以下交互式流程处理：
  1. 询问用户："我需要Unsplash API密钥才能搜索图片，你可以在https://unsplash.com/developers 免费获取密钥，请问你有密钥吗？"
  2. 等待用户提供密钥
  3. 将密钥保存到项目根目录的
    .env
    文件中：
    bash
    echo "UNSPLASH_ACCESS_KEY=<user_provided_key>" >> .env
  4. 重新运行原来的搜索/随机图片命令
本工具每次运行时会自动加载项目根目录下的
.env
文件。

Operations

功能操作

1. Search Photos

1. 搜索图片

Find photos by keyword with optional filters.
bash
./scripts/search.sh QUERY [PAGE] [PER_PAGE] [ORDER_BY] [ORIENTATION] [COLOR]
Parameters:
  • QUERY
    (required): Search keyword(s)
  • PAGE
    (optional, default: 1): Page number for pagination
  • PER_PAGE
    (optional, default: 10): Results per page (1-30)
  • ORDER_BY
    (optional, default: "relevant"): Sort order ("relevant" or "latest")
  • ORIENTATION
    (optional): Filter by orientation ("landscape", "portrait", "squarish")
  • COLOR
    (optional): Filter by color ("black_and_white", "black", "white", "yellow", "orange", "red", "purple", "magenta", "green", "teal", "blue")
Examples:
bash
undefined
按关键词查找图片，支持可选过滤条件。
bash
./scripts/search.sh QUERY [PAGE] [PER_PAGE] [ORDER_BY] [ORIENTATION] [COLOR]
参数说明：
  • QUERY
    （必填）：搜索关键词
  • PAGE
    （可选，默认值：1）：分页页码
  • PER_PAGE
    （可选，默认值：10）：每页返回结果数（1-30）
  • ORDER_BY
    （可选，默认值："relevant"）：排序方式（"relevant"相关度 / "latest"最新）
  • ORIENTATION
    （可选）：按图片方向过滤（"landscape"横版 / "portrait"竖版 / "squarish"方形）
  • COLOR
    （可选）：按颜色过滤（"black_and_white"黑白 / "black"黑 / "white"白 / "yellow"黄 / "orange"橙 / "red"红 / "purple"紫 / "magenta"洋红 / "green"绿 / "teal"青 / "blue"蓝）
示例：
bash
undefined

Basic search

基础搜索

./scripts/search.sh "mountain landscape"
./scripts/search.sh "mountain landscape"

Search with filters

带过滤条件的搜索

./scripts/search.sh "sunset" 1 5 latest landscape
./scripts/search.sh "sunset" 1 5 latest landscape

Search by color

按颜色搜索

./scripts/search.sh "flower" 1 10 relevant portrait red
undefined
./scripts/search.sh "flower" 1 10 relevant portrait red
undefined

2. Random Photos

2. 随机图片

Get random photos with optional filtering.
bash
./scripts/random.sh [QUERY] [COUNT] [ORIENTATION]
Parameters:
  • QUERY
    (optional): Topic/keyword to filter random photos
  • COUNT
    (optional, default: 1): Number of photos (1-30)
  • ORIENTATION
    (optional): Filter by orientation ("landscape", "portrait", "squarish")
Examples:
bash
undefined
获取随机图片，支持可选过滤条件。
bash
./scripts/random.sh [QUERY] [COUNT] [ORIENTATION]
参数说明：
  • QUERY
    （可选）：用于过滤随机图片的主题/关键词
  • COUNT
    （可选，默认值：1）：返回图片数量（1-30）
  • ORIENTATION
    （可选）：按图片方向过滤（"landscape"横版 / "portrait"竖版 / "squarish"方形）
示例：
bash
undefined

Single random photo

获取单张随机图片

./scripts/random.sh
./scripts/random.sh

Random photos by topic

按主题获取随机图片

./scripts/random.sh "architecture" 5
./scripts/random.sh "architecture" 5

Random landscape photos

获取横版随机自然风景图

./scripts/random.sh "nature" 3 landscape
undefined
./scripts/random.sh "nature" 3 landscape
undefined

3. Track Download

3. 下载跟踪

Track when a user downloads a photo (required by Unsplash API guidelines).
bash
./scripts/track.sh PHOTO_ID
When to call:
  • When user actually downloads/saves the image file
  • NOT when just viewing or displaying the photo
  • Helps photographers get credit for downloads
Example:
bash
./scripts/track.sh "abc123xyz"
跟踪用户的图片下载行为（Unsplash API规范要求）。
bash
./scripts/track.sh PHOTO_ID
调用时机：
  • 仅当用户实际下载/保存图片文件时调用
  • 仅查看或展示图片时不要调用
  • 该操作有助于摄影师获得下载量统计的相应权益
示例：
bash
./scripts/track.sh "abc123xyz"

Output Format

输出格式

All operations return JSON with complete photo information:
json
{
  "id": "abc123xyz",
  "description": "A beautiful sunset over mountains",
  "alt_description": "orange sunset behind mountain range",
  "urls": {
    "raw": "https://...",
    "full": "https://...",
    "regular": "https://...",
    "small": "https://...",
    "thumb": "https://..."
  },
  "width": 6000,
  "height": 4000,
  "color": "#f3a460",
  "blur_hash": "L8H2#8-;00~q4n",
  "photographer_name": "Jane Smith",
  "photographer_username": "janesmith",
  "photographer_url": "https://unsplash.com/@janesmith?utm_source=claude_skill&utm_medium=referral",
  "photo_url": "https://unsplash.com/photos/abc123xyz?utm_source=claude_skill&utm_medium=referral",
  "attribution_text": "Photo by Jane Smith on Unsplash",
  "attribution_html": "Photo by <a href=\"https://unsplash.com/@janesmith?utm_source=claude_skill&utm_medium=referral\">Jane Smith</a> on <a href=\"https://unsplash.com/?utm_source=claude_skill&utm_medium=referral\">Unsplash</a>"
}
所有操作都会返回包含完整图片信息的JSON：
json
{
  "id": "abc123xyz",
  "description": "A beautiful sunset over mountains",
  "alt_description": "orange sunset behind mountain range",
  "urls": {
    "raw": "https://...",
    "full": "https://...",
    "regular": "https://...",
    "small": "https://...",
    "thumb": "https://..."
  },
  "width": 6000,
  "height": 4000,
  "color": "#f3a460",
  "blur_hash": "L8H2#8-;00~q4n",
  "photographer_name": "Jane Smith",
  "photographer_username": "janesmith",
  "photographer_url": "https://unsplash.com/@janesmith?utm_source=claude_skill&utm_medium=referral",
  "photo_url": "https://unsplash.com/photos/abc123xyz?utm_source=claude_skill&utm_medium=referral",
  "attribution_text": "Photo by Jane Smith on Unsplash",
  "attribution_html": "Photo by <a href=\"https://unsplash.com/@janesmith?utm_source=claude_skill&utm_medium=referral\">Jane Smith</a> on <a href=\"https://unsplash.com/?utm_source=claude_skill&utm_medium=referral\">Unsplash</a>"
}

Image URLs

图片URL说明

The 
urls
object contains different sizes:
  • raw: Original unprocessed image
  • full: Full resolution (max width/height: 5472px)
  • regular: Web display size (1080px wide)
  • small: Thumbnail (400px wide)
  • thumb: Small thumbnail (200px wide)
Recommended: Use 
urls.regular
for most web content (best quality/size balance).
urls
对象包含不同尺寸的图片地址：
  • raw：原始未处理图片
  • full：全分辨率图片（最大宽/高：5472px）
  • regular：网页展示尺寸（宽1080px）
  • small：缩略图（宽400px）
  • thumb：小缩略图（宽200px）
推荐用法： 大多数网页内容使用
urls.regular
即可，能实现画质和文件大小的最佳平衡。

Attribution Requirements

署名要求

CRITICAL: Unsplash requires attribution for all image usage.
关键提醒： Unsplash要求所有使用其图片的场景都必须提供署名。

Always Include Attribution

必须包含署名

When presenting photos to users, you MUST include one of:
  1. attribution_text (for plain text contexts):
    Photo by Jane Smith on Unsplash
  2. attribution_html (for HTML/web contexts):
    html
    Photo by <a href="...">Jane Smith</a> on <a href="...">Unsplash</a>
向用户展示图片时，你必须提供以下任意一种署名信息：
  1. attribution_text（适用于纯文本场景）：
    Photo by Jane Smith on Unsplash
  2. attribution_html（适用于HTML/网页场景）：
    html
    Photo by <a href="...">Jane Smith</a> on <a href="...">Unsplash</a>

Placement Guidelines

放置规范

  • Place attribution near the image (below or in caption)
  • Make it visible and readable
  • Don't remove or hide the attribution
  • Attribution is required by Unsplash API terms
  • 署名需放在图片附近（下方或图片说明中）
  • 需清晰可见、易于阅读
  • 不得移除或隐藏署名
  • Unsplash API条款要求必须提供署名

Why Attribution Matters

署名的重要性

  • Gives credit to photographers
  • Required by Unsplash API terms of service
  • Violating attribution can result in API access suspension
  • 尊重摄影师的劳动成果，为其提供署名权益
  • 是Unsplash API服务条款的强制要求
  • 违反署名要求可能会导致API访问权限被暂停

Common Workflows

常见工作流

Blog Post Hero Image

博客文章头图

bash
undefined
bash
undefined

Search for relevant image

搜索相关图片

./scripts/search.sh "technology workspace" 1 3 latest landscape
./scripts/search.sh "technology workspace" 1 3 latest landscape

Present options to user with attribution

向用户展示带署名的可选图片

User selects one

用户选中某张图片后

Display image with attribution_html in blog post

在博客文章中使用attribution_html展示图片及署名

undefined
undefined

Gallery of Random Images

随机图片画廊

bash
undefined
bash
undefined

Get variety of images

获取多样化的图片

./scripts/random.sh "travel" 10
./scripts/random.sh "travel" 10

Display all images with their attributions

展示所有图片及对应的署名信息

undefined
undefined

Specific Color Palette

匹配特定配色

bash
undefined
bash
undefined

Search for images matching brand colors

搜索符合品牌配色的图片

./scripts/search.sh "abstract" 1 5 latest "" blue
undefined
./scripts/search.sh "abstract" 1 5 latest "" blue
undefined

Error Handling

错误处理

Missing API Key:
ERROR: UNSPLASH_ACCESS_KEY not set
→ See "Setup (Interactive)" section above. Ask user for key, save to 
.env
, and retry.
Rate Limit Exceeded:
ERROR: Rate limit exceeded (50/hour in demo mode)
Wait an hour or use production credentials with higher limits.
Invalid API Key:
ERROR: Invalid API key
Check that your API key is correct.
No Results:
json
[]
Empty array returned if no photos match search criteria.
缺少API密钥：
ERROR: UNSPLASH_ACCESS_KEY not set
→ 参考上方“交互式设置”章节，向用户索要密钥，保存到
.env
后重试。
超出速率限制：
ERROR: Rate limit exceeded (50/hour in demo mode)
等待1小时，或者使用速率限制更高的生产环境凭证。
API密钥无效：
ERROR: Invalid API key
检查你填写的API密钥是否正确。
无匹配结果：
json
[]
如果没有符合搜索条件的图片，会返回空数组。

Dependencies

依赖

Required tools (standard on macOS/Linux):
  • bash
    - Shell interpreter
  • curl
    - HTTP client
  • jq
    - JSON processor
Install jq if missing:
bash
undefined
需要的工具（macOS/Linux系统默认预装）：
  • bash
    - Shell解释器
  • curl
    - HTTP客户端
  • jq
    - JSON处理工具
如果缺少jq可执行以下命令安装：
bash
undefined

macOS

macOS

brew install jq
brew install jq

Ubuntu/Debian

Ubuntu/Debian

sudo apt-get install jq
undefined
sudo apt-get install jq
undefined

Rate Limits

速率限制

  • Demo mode: 50 requests/hour
  • Production mode: 5,000 requests/hour
Production mode requires:
  1. Creating an Unsplash app
  2. Getting app approval from Unsplash
  3. Using your production access key
  • 演示模式：每小时50次请求
  • 生产模式：每小时5000次请求
使用生产模式需要：
  1. 创建Unsplash应用
  2. 提交应用给Unsplash审核通过
  3. 使用你的生产环境访问密钥

Best Practices

最佳实践

  1. Use specific search terms - More specific queries yield better results
  2. Filter by orientation - Match your layout needs (landscape/portrait)
  3. Always include attribution - Required by API terms
  4. Use regular size for web - Best quality/performance balance
  5. Track actual downloads - Only call track.sh when user downloads
  6. Cache results - Don't re-search for the same keywords
  7. Respect rate limits - Monitor usage in demo mode
  1. 使用具体的搜索词：越精准的查询返回的结果匹配度越高
  2. 按图片方向过滤：匹配你的布局需求（横版/竖版）
  3. 始终提供署名：API条款的强制要求
  4. 网页使用regular尺寸：画质和加载性能的最佳平衡
  5. 仅跟踪实际下载行为：仅当用户下载图片时调用track.sh
  6. 缓存结果：相同关键词不要重复搜索
  7. 遵守速率限制：演示模式下注意监控请求用量

More Examples

更多示例

See detailed usage patterns in: 
examples/usage-examples.md
查看详细使用场景参考：
examples/usage-examples.md

Troubleshooting

故障排查

Scripts not executable:
bash
chmod +x scripts/*.sh
jq not found:
bash
brew install jq  # macOS
API errors:
  • Check internet connection
  • Verify API key is set correctly
  • Check rate limit hasn't been exceeded
  • Ensure photo_id is valid (for track.sh)
脚本无执行权限：
bash
chmod +x scripts/*.sh
找不到jq命令：
bash
brew install jq  # macOS
API错误：
  • 检查网络连接
  • 确认API密钥已正确设置
  • 检查是否超出速率限制
  • 确认photo_id有效（调用track.sh时）

Links

相关链接