Pexels

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.

Capabilities

Photos and videos share one unified API host family. Use photo search and curated feeds for stills; video search and popular-video feeds for motion. Fetch a single photo or video by numeric id when you already have one. Collections cover featured editor packs, your saved sets, and mixed photo/video media inside a collection (filter by media type and sort order).

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).
• Legacy video host — older integrations used a separate videos-only host prefix on the same domain. Prefer the unified photos+video surface; the legacy prefix still answers for some accounts but is not the supported path for new work.
• List responses are compact by default — search/list calls return slim rows (preview_url / download_link, duration, orientation, credit) unless full_detail=true. Single fetch by numeric photo or video ID returns the full upstream object.

Content creator workflow

Operational order for stock footage and b-roll:

1. Videos first — use video search for motion clips; photo search is for stills and thumbnails only.
2. Vertical short-form — orientation=portrait with max_duration around 15–30 for Reels, TikTok, and Shorts-style clips.
3. Keyword search — start broad ("cooking b-roll", "city night", "workspace timelapse") then narrow with duration and orientation filters. Pexels search is fuzzy; unrelated matches can appear — refine the query rather than assuming an empty catalog.
4. Curated packs — when keyword search feels noisy, list featured collections then open one with type=videos to browse editor-curated b-roll sets.
5. Pagination — default per_page is 15; raise to 25–40 only when the user needs more options on one page. Use page for the next batch.
6. Downloads — compact video rows include download_link (best HD MP4). Photo rows include download_url and preview_url. Link the Pexels page (url) and credit the creator when publishing.

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.