canonical: https://jentic.com/apis/pexels.com/pexels

# Pexels API

Jentic publishes the only agent-ready OpenAPI specification for Pexels API, keeping it validated and integration-ready. Access free stock photos and videos from the full Pexels content library programmatically. Search photos and videos by query with filters for orientation, size, color, and locale. Retrieve curated and popular content collections, access individual media by ID with multiple resolution URLs, and browse featured collections. Simple API key authentication with paginated results up to 80 items per page. Includes photographer attribution and alt text for accessibility.

## For AI agents

Search free stock photos and videos, retrieve curated collections, and access high-resolution media URLs with photographer attribution through Pexels' content library.

## Scope

Does not upload content, manage user accounts, or provide advanced editing tools - use for discovery, search, and retrieval of free stock photos and videos only.

## Capabilities

- Search photos by query with filters for orientation (landscape, portrait, square), size, color, and locale
- Search videos by query with orientation and size filters
- Retrieve curated photos selected by the Pexels editorial team
- Access popular videos with filters for minimum/maximum width, height, and duration
- Get specific photos or videos by ID with multiple resolution URLs
- Browse user collections and featured collections with media counts
- Retrieve all media within a collection filtered by type (photos or videos)
- Access photographer attribution, profile URLs, and alt text for each photo
- Paginate results up to 80 items per page with next/previous page URLs

## Use cases

### AI Agent Stock Photo Search

AI agents use the Pexels API through Jentic to search free stock photos by query, orientation, size, and color filters without managing API keys directly. The agent searches Jentic for 'find stock photos of nature', receives the `/v1/search` endpoint schema with filter parameters (query, orientation, size, color, per_page), and executes. Jentic handles API key injection so the agent never sees raw credentials. Results include photo URLs in 8 different sizes (original, large2x, large, medium, small, portrait, landscape, tiny) with photographer attribution.

Example prompt: Search for landscape-oriented photos of 'sunset' with an orange color palette, return the first 20 results with large resolution URLs and photographer attribution

### Video Content Discovery

Search Pexels' free stock video library by query with filters for orientation and size. Access popular videos filtered by minimum/maximum dimensions and duration. Each video includes multiple quality options (HD, SD, UHD), frame rates, video file URLs, and thumbnail previews. Ideal for content management systems, marketing automation tools, and media platforms that need high-quality video assets with clear licensing.

Example prompt: Search for videos of 'cityscape' with landscape orientation, filter for videos between 10-30 seconds duration, and return HD quality download links with thumbnails

### Curated and Popular Content

Access real-time curated photo collections selected by the Pexels editorial team and popular videos trending on the platform. Use this for homepage galleries, daily featured content, or inspiration feeds. Curated content is refreshed regularly, and popular videos are ranked by engagement. Both endpoints support pagination and return full media metadata including dimensions, photographer details, and attribution requirements.

Example prompt: Retrieve the first 40 curated photos from Pexels, then fetch 20 popular videos with minimum HD quality, and compile a daily featured content email

### Collection Management

Browse featured collections on Pexels and retrieve all media within a collection filtered by type (photos or videos). Collections include metadata like title, description, media count, and photo/video counts. Use this to build thematic galleries, organize content by topic, or integrate Pexels collections into content management systems. The `/v1/collections/{id}` endpoint supports type filtering and pagination.

Example prompt: List all featured collections on Pexels, then retrieve all photos from the 'Nature' collection and display them in a responsive gallery with photographer credits

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/search` | Search photos by query with filters for orientation, size, color, locale, and pagination |
| GET | `/v1/curated` | Retrieve curated photos selected by the Pexels editorial team with pagination |
| GET | `/v1/photos/{id}` | Get a specific photo by ID with all resolution URLs and photographer attribution |
| GET | `/videos/search` | Search videos by query with orientation, size, and locale filters |
| GET | `/videos/popular` | Retrieve popular videos with filters for minimum/maximum width, height, and duration |
| GET | `/videos/videos/{id}` | Get a specific video by ID with quality options (HD, SD, UHD) and video file URLs |
| GET | `/v1/collections/featured` | List all featured collections with media counts and descriptions |
| GET | `/v1/collections/{id}` | Retrieve all media within a collection filtered by type (photos or videos) |

## Key resources

- **Photos** — Stock photos with width, height, photographer attribution, alt text, average color, and source URLs in 8 resolutions
- **Videos** — Stock videos with duration, quality options (HD, SD, UHD), video files, thumbnails, and user attribution
- **Collections** — Curated sets of photos and videos with title, description, privacy status, and media counts
- **Photo Sources** — Photo URLs in multiple resolutions: original, large2x, large, medium, small, portrait, landscape, tiny
- **Video Files** — Video download links with quality level, dimensions, frame rate, and file type metadata

## Why Jentic

- **Setup:** Wiring the Pexels API by hand means passing your API key in the Authorization header on api.pexels.com and splitting requests across the photo and video search paths yourself. Through Jentic you install once, import the Pexels API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Pexels puts the resource id in the URL path (`/v1/photos/{id}`, `/videos/videos/{id}`, `/v1/collections/{id}`), so a rule can pin your agent to one photo, video, or collection; and since every exposed operation is a read, the agent only searches and retrieves stock media. You choose the operations it may call, so it is limited to the discovery and retrieval calls you allow.
- **Credential handling:** Your Pexels API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find free stock photos of mountains', and Jentic returns the matching Pexels operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Shutterstock API** — Shutterstock is a premium stock media service while Pexels offers free content
- **Flickr API** — A Pexels alternative for sourcing photos and videos, giving apps programmatic access to Flickr's vast community-driven image library.

## FAQ

### Why is there no official OpenAPI spec for Pexels API?

Pexels does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Pexels API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Pexels API use?

Pexels uses API key authentication passed in the Authorization header. Through Jentic, API keys are stored encrypted in your Jentic One instance and injected at execution time - agents never handle raw API keys.

### Are Pexels photos and videos free to use?

Yes. All photos and videos on Pexels are free to use under the Pexels License, which allows personal and commercial use without attribution (though attribution is appreciated). The API returns photographer attribution information in the response, which you should display when using the content.

### Can I filter photos by color with the Pexels API?

Yes. The `/v1/search` endpoint accepts a color parameter that can be a hex code (without #) or a color name. Use this to find photos matching a specific color palette or brand colors. For example, color=ff5733 returns photos with orange tones.

### How do I search for stock photos through the Pexels API via Jentic?

Search Jentic for 'find stock photos' or 'pexels search images', then load the `/v1/search` operation schema. Specify the query parameter and optional filters like orientation, size, and color, and Jentic handles API key injection. Results include photo URLs in 8 different sizes and photographer attribution. Install with pip install jentic run it through Jentic One, the self-hosted execution layer.

### What video quality options are available from the Pexels API?

Videos are available in multiple qualities: HD (high definition), SD (standard definition), and UHD (ultra-high definition / 4K). Each video includes a video_files array with links for each quality level, along with dimensions, frame rate, and file type. You can filter popular videos by minimum width, height, and duration.

### Can I limit what my agent is allowed to do with the Pexels API?

Yes. Jentic One runs self-hosted, so you decide which Pexels operations your agent may call and which credentials it may use. Because every exposed Pexels operation is a read, you can restrict the agent to just search and retrieval calls like `/v1/search`, `/v1/curated`, and `/videos/search`, and leave the rest off. And since Pexels puts the resource id in the URL path for `/v1/photos/{id}`, `/videos/videos/{id}`, and `/v1/collections/{id}`, a rule can pin the agent to a single photo, video, or collection.