unsplash-image

Unsplash 图片搜索与下载

搜索 Unsplash 图片、下载图片，并可选择添加文字叠加层。

工具位置

• 脚本：~/.agents/tools/unsplash-search.py
• 环境文件：~/.agents/tools/.env（包含 UNSPLASH_CLIENT_ID）

快速使用

搜索并下载一张随机匹配的图片

python ~/.agents/tools/unsplash-search.py \
  --query "nature landscape" \
  --output ./image.jpg

使用方向筛选条件

python ~/.agents/tools/unsplash-search.py \
  --query "coffee shop" \
  --orientation landscape \
  --output ./coffee.jpg

添加文字叠加层（标题和副标题）

python ~/.agents/tools/unsplash-search.py \
  --query "technology abstract" \
  --output ./cover.png \
  --title "My Blog Post Title" \
  --subtitle "A short description"

列出结果但不下载

python ~/.agents/tools/unsplash-search.py \
  --query "sunset" \
  --list

选择第一条结果，而不是随机选择

python ~/.agents/tools/unsplash-search.py \
  --query "mountains" \
  --pick first \
  --output ./mountains.jpg

CLI 选项

选项	说明
--query, -q	（必填） 搜索查询字符串
--output, -o	（必填，除非使用 --list） 输出文件路径
--orientation	筛选条件：landscape、portrait 或 squarish
--color	颜色筛选条件（例如：blue、green、red、black_and_white）
--pick	从结果中选择的方式：random（默认）或 first
--title	要叠加到图片上的标题文本
--subtitle	要叠加的副标题文本（仅在使用 --title 时生效）
--list	列出搜索结果，而不是下载
--count	要获取的结果数量，最多 30 条（默认：30）

文字叠加层

提供 --title 时，脚本会在图片底部区域添加文字叠加层，包括：

• 文字后方的半透明深色背景
• 带阴影的白色标题文字
• 灰色副标题文字（如果已提供）
• 自动换行和字体大小调整

需要 Pillow：pip install Pillow

依赖项

• requests（用于 API 调用和图片下载）
• Pillow（仅在使用带有 --title 的文字叠加层时需要）

如有需要，请安装：

pip install requests Pillow

输出

脚本会打印：

• 下载 URL
• 摄影师署名（Unsplash 要求提供）
• 保存的文件路径
• 应用文字叠加层后的确认信息

说明

• Unsplash API 指南要求注明来源。脚本会打印摄影师信息。
• 根据 Unsplash API 条款的要求，脚本会调用 Unsplash 的下载跟踪端点。
• 图片以“常规”画质下载（宽度为 1080px）。如需更高分辨率，请修改脚本以使用 urls.full 或 urls.raw。