Pexels Media Sourcing

Source high-quality, royalty-free images and videos from Pexels for design work, placeholders, or content creation.

Prerequisites

This skill requires the PEXELSAPIKEY environment variable to be set.

echo $PEXELS_API_KEY

If not set, obtain a free API key from https://www.pexels.com/api/

API Base URLs

• Photos: https://api.pexels.com/v1/
• Videos: https://api.pexels.com/videos/

Authentication

All requests require the Authorization header:

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

Photo Endpoints

Search Photos

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"

Curated Photos

Trending photos curated by the Pexels team (updated hourly):

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

Get Photo by ID

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

Video Endpoints

Search Videos

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"

Popular Videos

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"

Get Video by ID

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

Collections

Featured Collections

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

Collection Media

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

Type parameter: photos, videos, or omit for both.

Photo Sizes Available

Video Files Available

MANDATORY: Sidecar Metadata Files

For EVERY downloaded file, create a sidecar metadata file. This ensures proper attribution tracking and reuse.

Naming Convention

For mountain-sunset.jpg, create mountain-sunset.jpg.meta.json.

Photo Sidecar Content

{
  "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": {}
}

Video Sidecar Content

{
  "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": [],
  "video_pictures": [],
  "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": {}
}

Download Workflow

1. Search and Select

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

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

2. Download with Sidecar

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

DOWNLOAD_URL=$(echo "$PHOTO_DATA" | jq -r '.src.large')
FILENAME="pexels-$PHOTO_ID-large.jpg"

curl -L -o "$FILENAME" "$DOWNLOAD_URL"

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"

3. Download Video with Sidecar

VIDEO_ID=12345
VIDEO_DATA=$(curl -s -H "Authorization: $PEXELS_API_KEY" \
  "https://api.pexels.com/videos/videos/$VIDEO_ID")

DOWNLOAD_URL=$(echo "$VIDEO_DATA" | jq -r '.video_files[] | select(.quality=="hd") | .link' | head -1)
FILENAME="pexels-$VIDEO_ID-hd.mp4"

curl -L -o "$FILENAME" "$DOWNLOAD_URL"

echo "$VIDEO_DATA" | jq '{
  source: "pexels",
  type: "video",
  id: .id,
  url: .url,
  download_url: (.video_files[] | select(.quality=="hd") | .link),
  downloaded_quality: "hd",
  width: .width,
  height: .height,
  duration: .duration,
  user: .user,
  video_files: .video_files,
  video_pictures: .video_pictures,
  license: "Pexels License - Free for personal and commercial use",
  attribution: ("Video by " + .user.name + " on Pexels"),
  downloaded_at: (now | todate),
  api_response: .
}' > "$FILENAME.meta.json"

Rate Limits

• 200 requests/hour, 20,000 requests/month
• Check response headers: X-Ratelimit-Limit, X-Ratelimit-Remaining, X-Ratelimit-Reset

Attribution

While not legally required by the Pexels license, attribution is encouraged:

• Minimal: "Photo by [Photographer] on Pexels"
• With link: "Photo by [Photographer](photographerurl) on [Pexels](photourl)"
• HTML: Use the attribution_html from the sidecar file

Example Use Cases

Placeholder Images for UI Design

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

Hero Background Video

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"

Product Photography Backgrounds

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

Checklist

When using this skill:

• Verify PEXELSAPIKEY is set
• Choose appropriate endpoint (search, curated, popular, collection)
• Apply relevant filters (orientation, size, color, duration)
• Select appropriate resolution for use case
• Download file to appropriate location
• CREATE SIDECAR METADATA FILE (mandatory for every download)
• Consider attribution in final use