unsplash

Unsplash 照片搜索

从 Unsplash 搜索并获取高质量照片，自动添加署名。

快速开始

# Search for photos
./scripts/search.sh "sunset beach"

# Get random photos
./scripts/random.sh "nature" 3

# Track download (when user downloads)
./scripts/track.sh PHOTO_ID

设置（交互式）

**重要：**如果脚本返回 UNSPLASH_ACCESS_KEY not set，请进行交互式处理：

1. 询问用户：“我需要一个 Unsplash API 密钥来搜索照片。你可以在 https://unsplash.com/developers 免费获取密钥——你有密钥吗？”

2. 等待用户提供密钥

3. 将密钥保存到项目根目录下的 .env：

   echo "UNSPLASH_ACCESS_KEY=<user_provided_key>" >> .env
   

4. 重新运行原始搜索或随机获取命令

该技能每次运行时都会自动从项目根目录加载 .env。

操作

1. 搜索照片

按关键词查找照片，并可选择添加筛选条件。

./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"）

示例：

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

# Search with filters
./scripts/search.sh "sunset" 1 5 latest landscape

# Search by color
./scripts/search.sh "flower" 1 10 relevant portrait red

2. 随机获取照片

随机获取照片，并可选择添加筛选条件。

./scripts/random.sh [QUERY] [COUNT] [ORIENTATION]

参数：

• QUERY（可选）：用于筛选随机照片的主题／关键词
• COUNT（可选，默认值：1）：照片数量（1-30）
• ORIENTATION（可选）：按方向筛选（"landscape"、"portrait"、"squarish"）

示例：

# Single random photo
./scripts/random.sh

# Random photos by topic
./scripts/random.sh "architecture" 5

# Random landscape photos
./scripts/random.sh "nature" 3 landscape

3. 记录下载

记录用户下载照片的操作（Unsplash API 指南要求）。

./scripts/track.sh PHOTO_ID

调用时机：

• 用户实际下载／保存图片文件时
• 仅查看或展示照片时不要调用
• 帮助摄影师获得下载署名

示例：

./scripts/track.sh "abc123xyz"

输出格式

所有操作都会返回包含完整照片信息的 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>"
}

图片 URL

urls 对象包含不同尺寸：

• raw：未经处理的原始图片
• full：全分辨率（最大宽度／高度：5472px）
• regular：网页显示尺寸（宽 1080px）
• small：缩略图（宽 400px）
• thumb：小尺寸缩略图（宽 200px）

**建议：**大多数网页内容使用 urls.regular（质量与尺寸的平衡最佳）。

署名要求

**至关重要：**Unsplash 要求所有图片使用场景都必须署名。

始终添加署名

向用户展示照片时，必须包含以下内容之一：

1. attribution_text（用于纯文本场景）：

   Photo by Jane Smith on Unsplash
   

2. attribution_html（用于 HTML／网页场景）：

   Photo by <a href="...">Jane Smith</a> on <a href="...">Unsplash</a>
   

放置指南

• 将署名放在图片附近（下方或说明文字中）
• 确保署名清晰可读
• 不要删除或隐藏署名
• Unsplash API 条款要求添加署名

署名的重要性

• 向摄影师致谢
• Unsplash API 服务条款要求添加署名
• 违反署名要求可能导致 API 访问权限被暂停

常见工作流

博文主图

# Search for relevant image
./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

随机图片画廊

# Get variety of images
./scripts/random.sh "travel" 10

# Display all images with their attributions

特定配色方案

# Search for images matching brand colors
./scripts/search.sh "abstract" 1 5 latest "" blue

错误处理

缺少 API 密钥：

ERROR: UNSPLASH_ACCESS_KEY not set

→ 请参阅上方的“设置（交互式）”部分。向用户索取密钥，将其保存到 .env，然后重试。

超出速率限制：

ERROR: Rate limit exceeded (50/hour in demo mode)

等待一小时，或使用限制更高的生产凭据。

API 密钥无效：

ERROR: Invalid API key

检查 API 密钥是否正确。

无结果：

[]

如果没有符合搜索条件的照片，则会返回空数组。

依赖项

所需工具（macOS/Linux 上的标准工具）：

• bash - Shell 解释器
• curl - HTTP 客户端
• jq - JSON 处理器

如果缺少 jq，请安装：

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

速率限制

• 演示模式：每小时 50 个请求
• 生产模式：每小时 5,000 个请求

生产模式需要：

1. 创建 Unsplash 应用
2. 获得 Unsplash 的应用审批
3. 使用你的生产访问密钥

最佳实践

1. 使用具体的搜索词 - 查询越具体，结果越好
2. 按方向筛选 - 匹配你的布局需求（横向／纵向）
3. 始终注明来源 - API 条款要求注明来源
4. 网页使用常规尺寸 - 在质量与性能之间取得最佳平衡
5. 跟踪实际下载 - 仅在用户下载时调用 track.sh
6. 缓存结果 - 不要重复搜索相同的关键词
7. 遵守速率限制 - 在演示模式下监控用量

更多示例

详细用法示例请参阅：examples/usage-examples.md

故障排除

脚本无法执行：

chmod +x scripts/*.sh

未找到 jq：

brew install jq  # macOS

API 错误：

• 检查互联网连接
• 确认 API 密钥设置正确
• 检查是否已超过速率限制
• 确保 photo_id 有效（用于 track.sh）

链接

• Unsplash API 文档：https://unsplash.com/documentation
• 获取 API 密钥：https://unsplash.com/developers
• Unsplash 指南：https://help.unsplash.com/en/articles/2511245-unsplash-api-guidelines