130 lines
6.3 KiB
Markdown
130 lines
6.3 KiB
Markdown
---
|
||
name: pexels-api
|
||
description: 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.
|
||
|