moonlight-lupin/agent-skills/pexels-stock-photos

Pexels Stock Photos

Search and download free stock photos from the Pexels API (200 req/hr, 20k/month free). All content is free for commercial and non-commercial use; just credit the photographer and link to Pexels.

Routing: Pexels vs AI Generation

The key word test: if the user says photo, picture, stock image, or find/search → Pexels. If the user says generate, create, make, draw, or illustration → AI generation.

When to Use

• User asks for a "photo of X" or "stock image of Y"
• Building presentations (PPTX) that need real imagery
• Article/blog illustrations needing authentic photos
• Social media posts requiring professional photography
• Any request for "real" images vs AI-generated

Don't use for:

• AI art / creative generation → host's image generation tool
• Editing existing images → host's image editing skill
• Screenshots or diagrams → use appropriate tools

API Reference

Base URL: https://api.pexels.com/v1/ Auth: Authorization: <PEXELS_API_KEY> header

Endpoints

Search Parameters

Photo Resource src Sizes

Workflow

1. Search for photos

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

Parse the JSON response to present results to the user: photo ID, photographer, alt text, dimensions, and Pexels URL.

2. Download a photo

Use the `src` URLs from the search response — don't hand-construct images.pexels.com URLs (the slug/extension isn't guaranteed; Pexels' docs say to use src). Each photo object carries ready-made size variants (see the src table above).

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

Deliver the file to the user via the host's file delivery mechanism.

3. Present results

When showing search results, format as a table:

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

Include the Pexels URL so the user can preview before downloading.

Attribution

Per Pexels guidelines:

• Credit the photographer: "Photo by [Name] on Pexels"
• Link back to the photo page URL
• Include "Photos provided by Pexels" when displaying multiple

Example attribution block:

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

Common Pitfalls

1. API key not in environment. PEXELS_API_KEY must be set before making

requests. Load it from your environment or .env file before calling curl.

1. Using spaces in query. URL-encode spaces as + or %20.

singapore skyline → singapore+skyline.

1. Downloading original for previews. Original files can be 10MB+. Use

large or medium for previews, original only when the user needs full resolution.

1. Rate limit awareness. 200 req/hr, 20k/month — but only API calls

(search, curated, photo lookup) count. CDN downloads from the src URLs on images.pexels.com (no API key needed) do not count. Batch searches with per_page=15-80 to minimize API calls.

1. Not including attribution. Pexels requires visible credit to the

photographer and a link to Pexels. Always include attribution text when delivering photos.

1. Hand-built photo URLs. Don't construct images.pexels.com/photos/...

URLs yourself — the slug and extension aren't guaranteed across photos. Always download via the src.* URLs from the API response.

Verification Checklist

• [ ] PEXELS_API_KEY is set in the environment
• [ ] Search query returns results (check total_results > 0)
• [ ] Downloaded file exists and is non-empty
• [ ] Attribution text included with delivered photo
• [ ] Rate limit headers checked if making many requests (X-Ratelimit-Remaining)