# Pexels API

> Pexels returns stock photos and videos, available as a workflow and API.

Pexels Search photos returns matching photos and photographer details; it needs a subject query, optionally with orientation or page. Pexels Search videos returns matching videos and creator details; it needs a subject query, optionally with orientation or page.

- Page: https://fous.com/tools/pexels
- Handle: `@pexels`
- Category: [Media processing](https://fous.com/tools/category/media)
- Source website: https://pexels.com
- Last verified: Sep 29, 2026

## Methods

### Search photos

Operation `search_photos`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Search free stock photos on Pexels by subject, orientation, and page. Returns up to 80 photos in search order; Pexels may broaden searches with few exact matches.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `page` | integer | no | `2` | Results page, e.g. 2. |
| `query` | string | yes | `"desert landscape"` | What the photo should show, e.g. office teamwork. |
| `max_results` | integer | no | `6` | Most photos to return, e.g. 20. |
| `orientation` | string | no | `"portrait"` | Image orientation, e.g. landscape. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "page": {
      "type": "integer",
      "default": 1,
      "minimum": 1,
      "description": "Results page, e.g. 2.",
      "x-fous-developer": true,
      "examples": [
        2,
        3,
        1
      ]
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "What the photo should show, e.g. office teamwork.",
      "examples": [
        "desert landscape",
        "office teamwork",
        "coffee shop"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 80,
      "minimum": 1,
      "description": "Most photos to return, e.g. 20.",
      "x-fous-developer": true,
      "examples": [
        6,
        5,
        80
      ]
    },
    "orientation": {
      "enum": [
        "any",
        "landscape",
        "portrait",
        "square"
      ],
      "type": "string",
      "default": "any",
      "description": "Image orientation, e.g. landscape.",
      "examples": [
        "portrait",
        "landscape",
        "square"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "page": 2,
      "query": "desert landscape",
      "max_results": 6,
      "orientation": "portrait"
    },
    {
      "query": "office teamwork"
    },
    {
      "page": 3,
      "query": "office teamwork",
      "max_results": 5,
      "orientation": "landscape"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `photos` | array |  | Photos in Pexels search order. |
| `photos[].width` | integer | `4160` | Original photo width in pixels. |
| `photos[].height` | integer | `6240` | Original photo height in pixels. |
| `photos[].photo_id` | integer | `34187676` | Pexels photo ID. |
| `photos[].description` | string or null | `"A solitary tree stands in a wide, arid desert landscape under clear daylight."` | Photo alt text. |
| `photos[].licence_note` | string | `"Free to use under the Pexels License"` | Pexels licence summary. |
| `photos[].photographer` | string or null | `"Cafer SEVİNÇ"` | Photographer name. |
| `photos[].average_colour` | string or null | `"#8E8179"` | Approximate main colour as a hex code. |
| `photos[].photo_page_link` | string | `"https://www.pexels.com/photo/lone-tree-in-vast-desert-landscape-34187676/"` | Photo page on Pexels. |
| `photos[].large_image_link` | string | `"https://images.pexels.com/photos/34187676/pexels-photo-34187676.jpeg?auto=compress&cs=tinysrgb&w=1880"` | Image link about 1880 pixels wide. |
| `photos[].original_image_link` | string | `"https://images.pexels.com/photos/34187676/pexels-photo-34187676.jpeg"` | Original image link. |
| `photos[].photographer_profile_link` | string or null | `"https://www.pexels.com/@cafer-sevi-nc-2150308909/"` | Photographer Pexels profile link. |

**Example input**

```json
{
  "page": 2,
  "query": "desert landscape",
  "max_results": 6,
  "orientation": "portrait"
}
```

**Example output**

```json
{
  "photos": [
    {
      "width": 4160,
      "height": 6240,
      "photo_id": 34187676,
      "description": "A solitary tree stands in a wide, arid desert landscape under clear daylight.",
      "licence_note": "Free to use under the Pexels License",
      "photographer": "Cafer SEVİNÇ",
      "average_colour": "#8E8179",
      "photo_page_link": "https://www.pexels.com/photo/lone-tree-in-vast-desert-landscape-34187676/",
      "large_image_link": "https://images.pexels.com/photos/34187676/pexels-photo-34187676.jpeg?auto=compress&cs=tinysrgb&w=1880",
      "original_image_link": "https://images.pexels.com/photos/34187676/pexels-photo-34187676.jpeg",
      "photographer_profile_link": "https://www.pexels.com/@cafer-sevi-nc-2150308909/"
    },
    {
      "width": 4000,
      "height": 6000,
      "photo_id": 33393969,
      "description": "Captivating view of hanging rock formation in Charyn Canyon, Tamerlik, Kazakhstan.",
      "licence_note": "Free to use under the Pexels License",
      "photographer": "Naimish Verma",
      "average_colour": "#ADACA8",
      "photo_page_link": "https://www.pexels.com/photo/hanging-rock-formation-in-charyn-canyon-kazakhstan-33393969/",
      "large_image_link": "https://images.pexels.com/photos/33393969/pexels-photo-33393969.jpeg?auto=compress&cs=tinysrgb&w=1880",
      "original_image_link": "https://images.pexels.com/photos/33393969/pexels-photo-33393969.jpeg",
      "photographer_profile_link": "https://www.pexels.com/@naimish17/"
    }
  ]
}
```

### Search videos

Operation `search_videos`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Find free stock videos on Pexels by search words, with creator, duration, preview, and direct video file links. Results follow the order of Pexels video search; up to 80 videos can be collected starting at the selected results page.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `page` | integer | no | `2` | Pexels search page to start from, for example 2. |
| `query` | string | yes | `"city traffic at night"` | What the video should show, for example city traffic at night. |
| `max_results` | integer | no | `26` | Maximum number of videos to return, for example 20. |
| `orientation` | string | no | `"portrait"` | The video frame shape, for example portrait. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "page": {
      "type": "integer",
      "default": 1,
      "minimum": 1,
      "description": "Pexels search page to start from, for example 2.",
      "x-fous-developer": true,
      "examples": [
        2
      ]
    },
    "query": {
      "type": "string",
      "examples": [
        "city traffic at night"
      ],
      "minLength": 1,
      "description": "What the video should show, for example city traffic at night."
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 80,
      "minimum": 1,
      "description": "Maximum number of videos to return, for example 20.",
      "x-fous-developer": true,
      "examples": [
        26,
        3
      ]
    },
    "orientation": {
      "enum": [
        "any",
        "landscape",
        "portrait",
        "square"
      ],
      "type": "string",
      "default": "any",
      "description": "The video frame shape, for example portrait.",
      "examples": [
        "portrait",
        "square"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "query": "city traffic at night"
    },
    {
      "page": 2,
      "query": "mountain sunrise",
      "max_results": 26,
      "orientation": "portrait"
    },
    {
      "query": "city traffic at night",
      "max_results": 3,
      "orientation": "square"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `videos` | array |  | Matching videos in Pexels search order. |
| `videos[].width` | integer or null | `1920` | Width in pixels of the selected video file. |
| `videos[].height` | integer or null | `1080` | Height in pixels of the selected video file. |
| `videos[].length` | string or null | `"0:06"` | Duration formatted as minutes and seconds, or hours, minutes and seconds. |
| `videos[].video_id` | integer | `10433645` | Pexels video ID. |
| `videos[].description` | string or null | `"Capture of busy city junction with night traffic lights and car flow."` | Video description. |
| `videos[].creator_name` | string or null | `"Ming Z"` | Name of the video creator. |
| `videos[].licence_note` | string | `"Free to use under the Pexels License"` | Pexels video licence note. |
| `videos[].length_seconds` | integer or null | `6` | Video duration in seconds. |
| `videos[].video_file_link` | string or null | `"https://videos.pexels.com/video-files/10433645/10433645-hd_1920_1080_25fps.mp4"` | Direct link to an HD 1920 × 1080 MP4, or the largest available MP4. |
| `videos[].video_page_link` | string | `"https://www.pexels.com/video/night-traffic-on-junction-in-city-10433645/"` | Pexels page for this video. |
| `videos[].preview_image_link` | string or null | `"https://images.pexels.com/videos/10433645/pexels-photo-10433645.jpeg?auto=compress&cs=tinysrgb&w=1440"` | Video preview image link. |
| `videos[].creator_profile_link` | string or null | `"https://www.pexels.com/@ming-z-2773622/"` | Link to the creator’s Pexels profile. |

**Example input**

```json
{
  "query": "city traffic at night"
}
```

**Example output**

```json
{
  "videos": [
    {
      "width": 1920,
      "height": 1080,
      "length": "0:06",
      "video_id": 10433645,
      "description": "Capture of busy city junction with night traffic lights and car flow.",
      "creator_name": "Ming Z",
      "licence_note": "Free to use under the Pexels License",
      "length_seconds": 6,
      "video_file_link": "https://videos.pexels.com/video-files/10433645/10433645-hd_1920_1080_25fps.mp4",
      "video_page_link": "https://www.pexels.com/video/night-traffic-on-junction-in-city-10433645/",
      "preview_image_link": "https://images.pexels.com/videos/10433645/pexels-photo-10433645.jpeg?auto=compress&cs=tinysrgb&w=1440",
      "creator_profile_link": "https://www.pexels.com/@ming-z-2773622/"
    },
    {
      "width": 1920,
      "height": 1080,
      "length": "1:08",
      "video_id": 3727447,
      "description": "Timelapse of city traffic at night with bright city lights.",
      "creator_name": "German Korb",
      "licence_note": "Free to use under the Pexels License",
      "length_seconds": 68,
      "video_file_link": "https://videos.pexels.com/video-files/3727447/3727447-hd_1920_1080_30fps.mp4",
      "video_page_link": "https://www.pexels.com/video/time-lapse-video-of-traffic-on-a-main-road-at-night-3727447/",
      "preview_image_link": "https://images.pexels.com/videos/3727447/canada-cars-city-montreal-3727447.jpeg?auto=compress&cs=tinysrgb&w=1440",
      "creator_profile_link": "https://www.pexels.com/@german-korb-1920614/"
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@pexels",
  "visibility": "public",
  "operation": "search_photos",
  "version": 1,
  "input": {
    "page": 2,
    "query": "desert landscape",
    "max_results": 6,
    "orientation": "portrait"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@pexels\",\n  \"visibility\": \"public\",\n  \"operation\": \"search_photos\",\n  \"version\": 1,\n  \"input\": {\n    \"page\": 2,\n    \"query\": \"desert landscape\",\n    \"max_results\": 6,\n    \"orientation\": \"portrait\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@pexels",
  "visibility": "public",
  "operation": "search_photos",
  "version": 1,
  "input": {
    "page": 2,
    "query": "desert landscape",
    "max_results": 6,
    "orientation": "portrait"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/pexels`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `search_photos`: Search photos. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `search_videos`: Search videos. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-pexels https://api.fous.com/mcp/tools/pexels --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Find photos for a campaign concept
- Source video clips for a presentation
- Compare photo and video options by orientation
- Review creator and licence details before selecting media
- Collect image links for a content brief

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this Pexels tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a Pexels account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from pexels.com when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### How can I find photos of a subject?

Search photos takes a subject query and returns matching photos with descriptions, photographer names, and image links.

### How can I find videos about a subject?

Search videos takes a subject query and returns matching videos with creator names, durations, previews, and video file links.

### Can I filter results by orientation?

Yes. Search photos and Search videos both accept an orientation to find results in the image or video frame shape you want.

## Related

- [Unsplash API](https://fous.com/tools/unsplash.md): Discover photos shared on Unsplash.
- [Wikimedia Commons API](https://fous.com/tools/wikimedia-commons.md): Discover freely licensed photos and other images from Wikimedia Commons.
- [Pinterest API](https://fous.com/tools/pinterest.md): Pinterest helps people discover and save visual ideas, returning public search results from the first page and visible profile boards, with monthly views only when shown.
- [Google Search API](https://fous.com/tools/google-search.md): Google Search returns public web, image, job, event, related-question, and autocomplete results in Google’s order, with answers and details when available; results may be fewer, omit information, or be empty.
- [YouTube API](https://fous.com/tools/youtube.md): YouTube returns public video, caption, comment and channel details, company channels, and the latest weekly Top Songs chart; inferred dates and some counts may be approximate.
- [Vimeo API](https://fous.com/tools/vimeo.md): Watch and share videos on Vimeo.
- [Dailymotion API](https://fous.com/tools/dailymotion.md): Watch and share videos on Dailymotion.
- [Google Lens API](https://fous.com/tools/google-lens.md): Identify images and find visually similar pages online.
- [All Media processing tools](https://fous.com/tools/category/media)