troykelly/pexels-media

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 PEXELS_API_KEY environment variable to be set.

# Check if API key is available
echo $PEXELS_API_KEY

If not set, obtain a free API key from Pexels 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"

Parameters: | Parameter | Required | Values | |-----------|----------|--------| | query | Yes | Search term | | orientation | No | landscape, portrait, square | | size | No | large (24MP), medium (12MP), small (4MP) | | color | No | red, orange, yellow, green, turquoise, blue, violet, pink, brown, black, gray, white, or hex code (e.g., #ffffff) | | locale | No | en-US, pt-BR, es-ES, de-DE, fr-FR, ja-JP, zh-CN, ko-KR, etc. | | page | No | Page number (default: 1) | | per_page | No | Results per page (default: 15, max: 80) |

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"

Additional Video Parameters: | Parameter | Description | |-----------|-------------| | min_width | Minimum width in pixels | | min_height | Minimum height in pixels | | min_duration | Minimum duration in seconds | | max_duration | Maximum duration in seconds |

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

When downloading photos, these sizes are available in the API response:

| Key | Description | |-----|-------------| | original | Original size uploaded by photographer | | large2x | Width 940px, height doubled | | large | Width 940px | | medium | Height 350px | | small | Height 130px | | portrait | Width 800px, height 1200px | | landscape | Width 1200px, height 627px | | tiny | Width 280px, height 200px |

Video Files Available

Videos include multiple quality files in the response:

| Quality | Typical Resolution | |---------|-------------------| | hd | 1280x720 | | sd | 640x360 | | hls | Adaptive streaming | | Various | Full HD, 4K when available |

MANDATORY: Sidecar Metadata Files

CRITICAL REQUIREMENT: For EVERY downloaded file, you MUST create a sidecar metadata file.

Sidecar File Naming

For a downloaded file 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": {
    // Full original API response for this photo
  }
}

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

Download Workflow

1. Search and Select

# 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. Download with Sidecar

# 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"

Rate Limits

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

Attribution Best Practices

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

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

Example Use Cases

Placeholder Images for UI Design

# 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"

Hero Background Video

# 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"

Product Photography Backgrounds

# 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"

Checklist

When using this skill:

• [ ] Verify PEXELS_API_KEY 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)
• [ ] Consider attribution in final use

References

• Pexels API Documentation
• Pexels License
• Pexels API Help