website-ai-generator/Pexels.md

name, description

name	description
pexels-api	Domain knowledge for the Pexels stock photo and video API.

Pexels API

Pexels provides a large library of high-quality stock photos and videos licensed under the Pexels License (personal and commercial use, no attribution required but appreciated).

Data Model

Photo Resource

Field	Type	Description
id	integer	Unique numeric photo identifier
width	integer	Original width in pixels
height	integer	Original height in pixels
url	string	Pexels web page URL for this photo
photographer	string	Photographer display name
photographer_url	string	Photographer's Pexels profile URL
photographer_id	integer	Photographer's numeric ID
avg_color	string	Hex color (e.g. #978E82), useful as image placeholder
alt	string	Alt text describing the photo
liked	boolean	Whether the current user liked this photo
src	object	Pre-sized image URLs (see below)

src object sizes:

Key	Dimensions	Notes
original	Full resolution	Matches width×height
large2x	W 940 × H 650 @2x	Retina-ready
large	W 940 × H 650	Standard large
medium	H 350 (proportional)	Proportionally scaled
small	H 130 (proportional)	Thumbnail
portrait	W 800 × H 1200	Cropped portrait
landscape	W 1200 × H 627	Cropped landscape
tiny	W 280 × H 200	Smallest preview

Video Resource

Field	Type	Description
id	integer	Unique numeric video identifier
width	integer	Original width in pixels
height	integer	Original height in pixels
url	string	Pexels web page URL for this video
image	string	Video screenshot/poster URL
duration	integer	Duration in seconds
user	object	Videographer: id (int), name (str), url (str)
video_files	array	Available quality versions (see below)
video_pictures	array	Preview thumbnails: id, picture (URL), nr (index)

video_files element:

Field	Type	Description
id	integer	File variant ID
quality	string/null	"hd", "sd", "hls", or null
file_type	string	MIME type (e.g. video/mp4)
width	integer/null	Width (null for HLS)
height	integer/null	Height (null for HLS)
fps	number	Frames per second
link	string	Direct download URL
size	integer	File size in bytes

Collection Resource

Field	Type	Description
id	string	Alphanumeric collection identifier (e.g. "8xntbhr")
title	string	Collection name
description	string/null	Optional description
private	boolean	Whether the collection is private
media_count	integer	Total photos + videos
photos_count	integer	Number of photos
videos_count	integer	Number of videos

Entity Relationships

• A Photo belongs to a Photographer (via photographer_id).
• A Video belongs to a User/Videographer (via user.id).
• A Collection contains mixed Photo and Video objects. Collection media items include an extra type field ("Photo" or "Video") to discriminate.
• Collections are read-only via API — create/edit on pexels.com, iOS, or Android app.

API Endpoints

Photos (base: /v1/)

Endpoint	Method	Description
/v1/search?query=...	GET	Full-text search with orientation, size, color, locale filters
/v1/curated	GET	Trending editor-curated photos, updated hourly
/v1/photos/:id	GET	Single Photo by numeric ID

Videos (base: /v1/videos/)

Endpoint	Method	Description
/v1/videos/search?query=...	GET	Full-text search with orientation, size, locale filters
/v1/videos/popular	GET	Trending videos with min_width, min_height, min_duration, max_duration filters
/v1/videos/videos/:id	GET	Single Video by numeric ID

Collections (base: /v1/collections/)

Endpoint	Method	Description
/v1/collections/featured	GET	Editor-curated themed collections
/v1/collections	GET	Your saved collections
/v1/collections/:id	GET	All media in a collection, filterable by type (photos/videos) and sort (asc/desc)

Pagination

All list endpoints accept page (default 1) and per_page (default 15, max 80). Responses include page, per_page, total_results, and optional next_page/prev_page URL strings. The total_results for search endpoints is capped at a high number (e.g. 8000) even when more results exist.

Rate Limits

• Default: 200 requests/hour, 20,000 requests/month.
• Response headers: X-Ratelimit-Limit (monthly quota), X-Ratelimit-Remaining, X-Ratelimit-Reset (UNIX timestamp for monthly rollover).
• Rate limit headers are only returned on successful (2xx) responses, not on 429 errors.
• Higher limits available with proper attribution — contact api@pexels.com.

Search Tips & Gotchas

• Queries can be broad ("nature", "people") or specific ("group of people working").
• Color filter (photos only): Named colors (red, orange, yellow, green, turquoise, blue, violet, pink, brown, black, gray, white) or hex codes (e.g. #ffffff).
• Locale affects search relevance for non-English queries. Supported: en-US, pt-BR, es-ES, ca-ES, de-DE, it-IT, fr-FR, sv-SE, id-ID, pl-PL, ja-JP, zh-TW, zh-CN, ko-KR, th-TH, nl-NL, hu-HU, vi-VN, cs-CZ, da-DK, fi-FI, uk-UA, el-GR, ro-RO, nb-NO, sk-SK, tr-TR, ru-RU.
• Size filter means different things: for photos, large = 24MP+, medium = 12MP+, small = 4MP+; for videos, large = 4K, medium = Full HD, small = HD.
• Video quality field may be null for newer video files — use width/height to determine actual resolution.
• Collection IDs are alphanumeric strings (not integers like photo/video IDs).
• The deprecated video base URL https://api.pexels.com/videos/ still works but should not be used — use /v1/videos/ instead.

Attribution

Best practice: link to the photo/video page on Pexels and credit the photographer/videographer (e.g. "Photo by John Doe on Pexels"). Use the url field from the response for attribution links.