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 のガイドラインではクレジット表記が必要です。スクリプトは撮影者の情報を出力します。
• スクリプトは、API 利用規約の要件に従って Unsplash のダウンロード追跡エンドポイントを呼び出します。
• 画像は「regular」品質（幅 1080px）でダウンロードされます。より高解像度にするには、スクリプトを変更して urls.full または urls.raw を使用してください。