pexels-stock-photos

Pexels ストックフォト

Pexels API から無料のストックフォトを検索してダウンロードします（1 時間あたり 200 リクエスト、月あたり 20,000 リクエストまで無料）。すべてのコンテンツは商用・非商用を問わず無料で利用できます。写真家のクレジットを表記し、Pexels にリンクしてください。

ルーティング：Pexels と AI 生成

ユーザーの発言	ツール
「シンガポールの写真を探して」／「オフィスの写真を検索して」／「机のストック画像」	Pexels（このスキル）
「このスライドに使う実際の写真が必要」／「記事用の写真を探して」	Pexels（このスキル）
「猫の画像を生成して」／「…の画像を作って」／「イラストを描いて」	ホストの画像生成ツール
「これをアップスケールして」／「背景を削除して」／「編集：暖かみのある色合いにして」	ホストの AI 画像編集スキル
「本番環境向けの高品質なヒーロー画像」／「きちんと作り込みたい」	ホストの複数段階画像生成スキル

キーワードの見分け方： ユーザーが 写真、画像、ストック画像、または 探す／検索する と言った場合 → Pexels。生成する、作成する、作る、描く、または イラスト と言った場合 → AI 生成。

使用する場面

• ユーザーが「X の写真」または「Y のストック画像」を求めている
• 実際の画像が必要なプレゼンテーション（PPTX）を作成する
• 本物らしい写真を使った記事やブログの挿絵が必要
• プロ品質の写真が必要なソーシャルメディアの投稿
• AI 生成ではなく「実際の」画像を求めている場合

使用しない場面：

• AI アートやクリエイティブな画像生成 → ホストの画像生成ツール
• 既存画像の編集 → ホストの画像編集スキル
• スクリーンショットや図表 → 適切なツールを使用

API リファレンス

ベース URL：https://api.pexels.com/v1/ 認証：Authorization: <PEXELS_API_KEY> ヘッダー

エンドポイント

エンドポイント	メソッド	目的
/search	GET	クエリで写真を検索
/curated	GET	厳選された人気の写真を取得
/photos/:id	GET	ID を指定して写真を取得

検索パラメーター

パラメーター	型	デフォルト	備考
query	string	必須	例：「singapore skyline」
orientation	string	—	landscape、portrait、square
size	string	—	large（24MP）、medium（12MP）、small（4MP）
color	string	—	red、orange、blue、…、または 16 進数の #ffffff
locale	string	en-US	zh-CN、ja-JP など
per_page	int	15	最大 80
page	int	1	ページネーション

写真リソースの src サイズ

サイズ	寸法	用途
original	フル解像度	印刷、高品質
large2x	940×650 @2x	Retina ディスプレイ
large	940×650	ウェブ、プレゼンテーション
medium	高さ約 350px	サムネイル、プレビュー
small	高さ約 130px	小さなサムネイル
portrait	800×1200	縦向き／モバイル
landscape	1200×627	スライド、ソーシャルメディア
tiny	280×200	プレースホルダー

ワークフロー

1. 写真を検索する

curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/search?query=singapore+skyline&per_page=5&orientation=landscape"

JSON レスポンスを解析し、写真 ID、写真家、代替テキスト、寸法、Pexels URL をユーザーに提示します。

2. 写真をダウンロードする

検索レスポンスの src URL を使用してください。images.pexels.com の URL を手作業で組み立てないでください（スラッグや拡張子は保証されていません。Pexels のドキュメントでも src の使用が推奨されています）。各写真オブジェクトには、すぐに使えるサイズ別の画像 URL が含まれています（上の src 表を参照）。

# Download the size you need, straight from the photo's src field
# (e.g. the value of photos[0].src.large from the search JSON)
curl -sL -o /tmp/pexels_<id>.jpeg "<photo.src.large>"

ホストのファイル配信機能を使って、ファイルをユーザーに渡します。

3. 検索結果を提示する

検索結果を表示するときは、次のように表形式で提示します。

| # | ID | Photographer | Alt | Dimensions |
|---|-----|-------------|-----|------|
| 1 | 5097071 | Dylan Chan | Singapore skyline at dusk | 6016×3384 |

ダウンロード前にユーザーがプレビューできるよう、Pexels URL を含めます。

クレジット表記

Pexels のガイドラインに従ってください。

• 写真家のクレジットを表記します：「Photo by [Name] on Pexels」
• 写真ページの URL にリンクします
• 複数の写真を表示する場合は、「Photos provided by Pexels」を含めます

クレジット表記の例：

Photo by Dylan Chan on Pexels
https://www.pexels.com/photo/high-rise-buildings-in-singapore-5097071/

よくある落とし穴

1. API キーが環境変数に設定されていない。 リクエストを行う前に、PEXELS_API_KEY を設定する必要があります。curl を呼び出す前に、環境変数または .env ファイルから読み込んでください。

2. 検索クエリにスペースを使用している。 スペースは + または %20 に URL エンコードしてください。 singapore skyline → singapore+skyline。

3. プレビュー用にオリジナルをダウンロードしている。 オリジナルのファイルは 10MB 以上になることがあります。プレビューには large または medium を使用し、ユーザーがフル解像度を必要とする場合にのみ original を使用してください。

4. レート制限への配慮。 1 時間あたり 200 リクエスト、月あたり 20,000 リクエストです。ただし、カウントされるのは API 呼び出し（検索、キュレート、写真の検索）のみです。images.pexels.com 上の src URL からの CDN ダウンロード（API キー不要）はカウントされません。API 呼び出しを最小限に抑えるため、per_page=15-80 で検索をまとめて行ってください。

5. クレジット表記を含めていない。 Pexels では、写真家への目に見える形でのクレジット表記と Pexels へのリンクが必要です。写真を提供する際は、必ずクレジット表記を含めてください。

6. 写真 URL を手作業で作成している。 images.pexels.com/photos/... の URL を自分で作成しないでください。スラッグと拡張子は写真ごとに保証されていません。必ず API レスポンスの src.* URL からダウンロードしてください。

検証チェックリスト

• 環境変数に PEXELS_API_KEY が設定されている
• 検索クエリで結果が返される（total_results > 0 を確認）
• ダウンロードしたファイルが存在し、空ではない
• 提供する写真にクレジット表記が含まれている
• 多数のリクエストを行う場合は、レート制限ヘッダー（X-Ratelimit-Remaining）を確認している