unsplash-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unsplash Image Search & Download

Unsplash图片搜索与下载

Search Unsplash for images, download them, and optionally add text overlay.

在Unsplash上搜索图片、下载图片，还可选择添加文字覆盖层。

Tool Location

工具位置

Script:
```
~/.agents/tools/unsplash-search.py
```
Env file:
```
~/.agents/tools/.env
```
(contains
```
UNSPLASH_CLIENT_ID
```
)

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

Quick Usage

快速使用

Search and download a random matching image

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

bash

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

bash

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

With orientation filter

带方向筛选

bash

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

bash

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

With text overlay (title and subtitle)

带文字覆盖层（标题和副标题）

bash

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

bash

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

List results without downloading

仅列出结果不下载

bash

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

bash

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

Pick the first result instead of random

选择第一个结果而非随机

bash

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

bash

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

CLI Options

CLI选项

Option	Description
`--query, -q`	(Required) Search query string
`--output, -o`	(Required unless --list) Output file path
`--orientation`	Filter: `landscape` , `portrait` , or `squarish`
`--color`	Color filter (e.g., `blue` , `green` , `red` , `black_and_white` )
`--pick`	How to select from results: `random` (default) or `first`
`--title`	Title text to overlay on the image
`--subtitle`	Subtitle text to overlay (only used with --title)
`--list`	List search results instead of downloading
`--count`	Number of results to fetch, max 30 (default: 30)

选项	描述
`--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）

Text Overlay

文字覆盖层

When

--title

is provided, the script adds a text overlay to the bottom portion of the image with:

Semi-transparent dark background behind the text
White title text with shadow
Gray subtitle text (if provided)
Automatic word wrapping and font sizing

Requires Pillow:

pip install Pillow

当提供

--title

参数时，脚本会在图片底部添加文字覆盖层，包含：

文字背后的半透明深色背景
带阴影的白色标题文字
灰色副标题文字（若提供）
自动换行和字体大小适配

依赖Pillow：

pip install Pillow

Dependencies

依赖项

```
requests
```
(for API calls and image download)
```
Pillow
```
(only needed if using text overlay with
```
--title
```
)

Install if needed:

bash

pip install requests Pillow

```
requests
```
（用于API调用和图片下载）
```
Pillow
```
（仅在使用
```
--title
```
添加文字覆盖层时需要）

若需安装，执行：

bash

pip install requests Pillow

Output

输出

The script prints:

The download URL
Photographer attribution (required by Unsplash)
The saved file path
Confirmation of text overlay if applied

脚本会打印：

下载链接
摄影师署名（Unsplash要求必填）
文件保存路径
若添加了文字覆盖层，会给出确认信息

Notes

注意事项

Unsplash API guidelines require attribution. The script prints photographer info.
The script triggers Unsplash's download tracking endpoint as required by their API terms.
Images are downloaded at "regular" quality (1080px width). For higher resolution, modify the script to use
```
urls.full
```
or
```
urls.raw
```
.

Unsplash API指南要求署名，脚本会打印摄影师信息。
脚本会触发Unsplash的下载跟踪端点，符合其API条款要求。
图片以“常规”质量（宽度1080px）下载。如需更高分辨率，可修改脚本使用
```
urls.full
```
或
```
urls.raw
```
。