pexels-media

Pexels のメディア調達

デザイン作業、プレースホルダー、コンテンツ作成のために、Pexels から高品質でロイヤリティフリーの画像や動画を取得します。

前提条件

このスキルを使用するには、環境変数 PEXELS_API_KEY を設定する必要があります。

# Check if API key is available
echo $PEXELS_API_KEY

設定されていない場合は、Pexels API から無料の API キーを取得してください。

API のベース URL

• 写真：https://api.pexels.com/v1/
• 動画：https://api.pexels.com/videos/

認証

すべてのリクエストで Authorization ヘッダーが必要です。

curl -H "Authorization: $PEXELS_API_KEY" "https://api.pexels.com/v1/search?query=nature"

写真のエンドポイント

写真を検索

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/search?query=QUERY&orientation=ORIENTATION&size=SIZE&color=COLOR&locale=LOCALE&page=PAGE&per_page=PER_PAGE"

パラメーター：

パラメーター	必須	値
query	はい	検索語
orientation	いいえ	landscape、portrait、square
size	いいえ	large（24MP）、medium（12MP）、small（4MP）
color	いいえ	red、orange、yellow、green、turquoise、blue、violet、pink、brown、black、gray、white、または 16 進数コード（例：#ffffff）
locale	いいえ	en-US、pt-BR、es-ES、de-DE、fr-FR、ja-JP、zh-CN、ko-KR など
page	いいえ	ページ番号（デフォルト：1）
per_page	いいえ	1 ページあたりの結果数（デフォルト：15、最大：80）

厳選された写真

Pexels チームが厳選した人気の写真です（1 時間ごとに更新）：

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/curated?page=1&per_page=15"

ID で写真を取得

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/photos/PHOTO_ID"

動画のエンドポイント

動画を検索

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/videos/search?query=QUERY&orientation=ORIENTATION&size=SIZE&min_width=MIN_WIDTH&min_height=MIN_HEIGHT&min_duration=MIN_DURATION&max_duration=MAX_DURATION&page=PAGE&per_page=PER_PAGE"

動画の追加パラメーター：

パラメーター	説明
min_width	最小幅（ピクセル）
min_height	最小の高さ（ピクセル）
min_duration	最短の長さ（秒）
max_duration	最長の長さ（秒）

人気の動画

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/videos/popular?min_width=1920&min_duration=10&max_duration=60&page=1&per_page=15"

ID で動画を取得

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/videos/videos/VIDEO_ID"

コレクション

注目のコレクション

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/collections/featured?page=1&per_page=15"

コレクションのメディア

curl -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/collections/COLLECTION_ID?type=TYPE&page=1&per_page=15"

type パラメーター： photos、videos、または省略すると両方が対象になります。

利用可能な写真のサイズ

写真をダウンロードする際、API レスポンスでは次のサイズを利用できます。

キー	説明
original	写真家がアップロードした元のサイズ
large2x	幅 940px、高さはその 2 倍
large	幅 940px
medium	高さ 350px
small	高さ 130px
portrait	幅 800px、高さ 1200px
landscape	幅 1200px、高さ 627px
tiny	幅 280px、高さ 200px

利用可能な動画ファイル

動画のレスポンスには、複数の品質のファイルが含まれます。

品質	一般的な解像度
hd	1280x720
sd	640x360
hls	アダプティブストリーミング
各種	利用可能な場合はフル HD、4K

必須：サイドカーメタデータファイル

重要な要件： ダウンロードしたファイルごとに、必ずサイドカーメタデータファイルを作成してください。

サイドカーファイルの命名

mountain-sunset.jpg をダウンロードした場合は、mountain-sunset.jpg.meta.json を作成します。

写真のサイドカー内容

{
  "source": "pexels",
  "type": "photo",
  "id": 12345,
  "url": "https://www.pexels.com/photo/12345/",
  "download_url": "https://images.pexels.com/photos/12345/pexels-photo-12345.jpeg",
  "downloaded_size": "large",
  "width": 1920,
  "height": 1080,
  "photographer": "John Doe",
  "photographer_url": "https://www.pexels.com/@johndoe",
  "photographer_id": 67890,
  "avg_color": "#7E5835",
  "alt": "Brown mountain during sunset",
  "license": "Pexels License - Free for personal and commercial use",
  "attribution": "Photo by John Doe on Pexels",
  "attribution_html": "<a href=\"https://www.pexels.com/photo/12345/\">Photo</a> by <a href=\"https://www.pexels.com/@johndoe\">John Doe</a> on <a href=\"https://www.pexels.com\">Pexels</a>",
  "downloaded_at": "2025-12-02T14:30:00Z",
  "api_response": {
    // Full original API response for this photo
  }
}

動画のサイドカー内容

{
  "source": "pexels",
  "type": "video",
  "id": 12345,
  "url": "https://www.pexels.com/video/12345/",
  "download_url": "https://videos.pexels.com/video-files/12345/...",
  "downloaded_quality": "hd",
  "width": 1920,
  "height": 1080,
  "duration": 30,
  "user": {
    "id": 67890,
    "name": "John Doe",
    "url": "https://www.pexels.com/@johndoe"
  },
  "video_files": [
    {
      "id": 1,
      "quality": "hd",
      "file_type": "video/mp4",
      "width": 1920,
      "height": 1080,
      "link": "https://..."
    }
  ],
  "video_pictures": [
    {
      "id": 1,
      "picture": "https://...",
      "nr": 0
    }
  ],
  "license": "Pexels License - Free for personal and commercial use",
  "attribution": "Video by John Doe on Pexels",
  "downloaded_at": "2025-12-02T14:30:00Z",
  "api_response": {
    // Full original API response for this video
  }
}

ダウンロードのワークフロー

1. 検索して選択

# Search for photos
RESPONSE=$(curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/search?query=office+workspace&orientation=landscape&per_page=5")

# Parse and display results
echo "$RESPONSE" | jq '.photos[] | {id, photographer, alt, url: .src.large}'

2. サイドカーとともにダウンロード

# Get photo details
PHOTO_ID=12345
PHOTO_DATA=$(curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/photos/$PHOTO_ID")

# Extract download URL (choose size)
DOWNLOAD_URL=$(echo "$PHOTO_DATA" | jq -r '.src.large')
FILENAME="pexels-$PHOTO_ID-large.jpg"

# Download the image
curl -L -o "$FILENAME" "$DOWNLOAD_URL"

# Create sidecar metadata (MANDATORY)
echo "$PHOTO_DATA" | jq '{
  source: "pexels",
  type: "photo",
  id: .id,
  url: .url,
  download_url: .src.large,
  downloaded_size: "large",
  width: .width,
  height: .height,
  photographer: .photographer,
  photographer_url: .photographer_url,
  photographer_id: .photographer_id,
  avg_color: .avg_color,
  alt: .alt,
  license: "Pexels License - Free for personal and commercial use",
  attribution: ("Photo by " + .photographer + " on Pexels"),
  downloaded_at: (now | todate),
  api_response: .
}' > "$FILENAME.meta.json"

レート制限

• デフォルト： 1 時間あたり 200 リクエスト、1 か月あたり 20,000 リクエスト
• 現在の制限については、レスポンスヘッダーを確認してください。
  • X-Ratelimit-Limit
  • X-Ratelimit-Remaining
  • X-Ratelimit-Reset

クレジット表記のベストプラクティス

Pexels のライセンス上、クレジット表記は必須ではありませんが、推奨されています。

• 最小限： 「Photo by [Photographer] on Pexels」
• リンク付き： 「Photo by Photographer on Pexels」
• HTML： サイドカーファイルの attribution_html を使用します

使用例

UI デザイン用のプレースホルダー画像

# Get 5 abstract/minimal images for placeholders
curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/search?query=minimal+abstract&orientation=square&size=small&per_page=5"

ヒーロー背景動画

# Find short, wide landscape videos
curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/videos/search?query=nature+aerial&orientation=landscape&min_width=1920&min_duration=5&max_duration=15"

商品写真の背景

# Search for clean, neutral backgrounds
curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/v1/search?query=white+background+texture&color=white&size=large"

チェックリスト

このスキルを使用する際は、次の点を確認してください。

• PEXELS_API_KEY が設定されていることを確認する
• 適切なエンドポイント（検索、厳選、人気、コレクション）を選ぶ
• 関連するフィルター（向き、サイズ、色、長さ）を適用する
• 用途に適した解像度を選ぶ
• ファイルを適切な場所にダウンロードする
• サイドカーメタデータファイルを作成する（必須）
• 最終的な用途でクレジット表記を検討する

References

• Pexels API Documentation
• Pexels License
• Pexels API Help