mcpField
U
unsplash

unsplash

github.com/cevatkerimクリエイティブ・メディア0552 回インストール40 週間前に更新
リポジトリ

unsplash について

Unsplashの写真を検索・取得するシェルスクリプトのスキルです。画像候補と撮影者のクレジットが必要な作業に向き、実際のダウンロードも記録できます。

主な機能

  1. 01キーワードと条件で検索
  2. 02ランダム写真の取得
  3. 03写真ダウンロードの記録
  4. 04写真情報とクレジットの出力

活用シーン

  1. 01ブログ記事のメイン画像探し
  2. 02テーマ別写真ギャラリーの作成
  3. 03向きや色に合わせた写真選び

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/cevatkerim/skills --skill unsplash

インストール後、Claude Code で/unsplashを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

.env.example
.gitignore
install.sh
README.md
examples/
usage-examples.md
scripts/
random.sh
search.sh
track.sh
scripts/lib/
common.sh

詳細

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)

1時間待つか、制限の高い本番用認証情報を使用してください。

API キーが無効です：

ERROR: Invalid API key

API キーが正しいことを確認してください。

結果がありません：

[]

検索条件に一致する写真がない場合は、空の配列が返されます。

依存関係

必要なツール（macOS／Linux の標準ツール）：

  • bash - シェルインタープリター
  • curl - HTTP クライアント
  • jq - JSON プロセッサー

jq がない場合はインストールしてください：

# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

レート制限

  • デモモード：1時間あたり50リクエスト
  • 本番モード：1時間あたり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 の場合）

リンク

コメント

Markdown 対応