Pexels API: Search photos
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.
Unofficial. Not affiliated with or endorsed by Pexels.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- Page optional
page Results page, e.g. 2.
1 (default)
Whole number 1 or more.
- Query, required
query What the photo should show, e.g. office teamwork.
office teamwork
- Max Results optional
max_results Most photos to return, e.g. 20.
20 (default)
Whole number from 1 to 80.
- Orientation optional
orientation Image orientation, e.g. landscape.
any (default)
One of
any,landscape,portrait,square.
Input as JSON
{ "query": "office teamwork"}Output
{ "photos": [ { "width": 5236, "height": 3491, "photo_id": 6192762, "description": "Arrangement of office supplies around teamwork text on black background.", "licence_note": "Free to use under the Pexels License", "photographer": "KATRIN BOLOVTSOVA", "average_colour": "#080F18", "photo_page_link": "https://www.pexels.com/photo/silver-and-black-pens-on-a-black-surface-6192762/" , "large_image_link": "https://images.pexels.com/photos/6192762/pexels-photo-6192762.jpeg?auto=compress&cs=tinysrgb&w=1880" , "original_image_link": "https://images.pexels.com/photos/6192762/pexels-photo-6192762.jpeg" , "photographer_profile_link": "https://www.pexels.com/@ekaterina-bolovtsova/" }, { "width": 3690, "height": 5535, "photo_id": 8276211, "description": "Coworkers joining fists over office desk, symbolizing teamwork and motivation.", "licence_note": "Free to use under the Pexels License", "photographer": "PNW Production", "average_colour": "#726253", "photo_page_link": "https://www.pexels.com/photo/close-up-of-coworkers-in-an-office-fistbumping-8276211/" , "large_image_link": "https://images.pexels.com/photos/8276211/pexels-photo-8276211.jpeg?auto=compress&cs=tinysrgb&w=1880" , "original_image_link": "https://images.pexels.com/photos/8276211/pexels-photo-8276211.jpeg" , "photographer_profile_link": "https://www.pexels.com/@pnw-prod/" }, { "width": 4000, "height": 6000, "photo_id": 12903168, "description": "Professional team collaborating on a project in a well-lit office space.", "licence_note": "Free to use under the Pexels License", "photographer": "Mizuno K", "average_colour": "#9D9C98", "photo_page_link": "https://www.pexels.com/photo/employees-cooperating-in-office-12903168/" , "large_image_link": "https://images.pexels.com/photos/12903168/pexels-photo-12903168.jpeg?auto=compress&cs=tinysrgb&w=1880" , "original_image_link": "https://images.pexels.com/photos/12903168/pexels-photo-12903168.jpeg" , "photographer_profile_link": "https://www.pexels.com/@mizunokozuki/" } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"pexels.com/search_photos","input":{"query":"office teamwork"}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "pexels.com/search_photos" , "input": { "query": "office teamwork" }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "pexels.com/search_photos" , "input": { "query": "office teamwork" } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run pexels.com/search_photos# with {"query":"office teamwork"}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [ "query" ], "properties": { "page": { "type": "integer", "default": 1, "minimum": 1, "description": "Results page, e.g. 2." }, "query": { "type": "string", "minLength": 1, "description": "What the photo should show, e.g. office teamwork." }, "max_results": { "type": "integer", "default": 20, "maximum": 80, "minimum": 1, "description": "Most photos to return, e.g. 20." }, "orientation": { "enum": [ "any", "landscape", "portrait", "square" ], "type": "string", "default": "any", "description": "Image orientation, e.g. landscape." } }}Output schema
{ "type": "object", "required": [ "photos" ], "properties": { "photos": { "type": "array", "items": { "type": "object", "required": [ "description", "photographer", "photographer_profile_link", "large_image_link", "original_image_link", "width", "height", "licence_note", "photo_page_link", "photo_id", "average_colour" ], "properties": { "width": { "type": "integer", "description": "Original photo width in pixels." }, "height": { "type": "integer", "description": "Original photo height in pixels." }, "photo_id": { "type": "integer", "description": "Pexels photo ID." }, "description": { "type": [ "string", "null" ], "description": "Photo alt text." }, "licence_note": { "type": "string", "description": "Pexels licence summary." }, "photographer": { "type": [ "string", "null" ], "description": "Photographer name." }, "average_colour": { "type": [ "string", "null" ], "description": "Approximate main colour as a hex code." }, "photo_page_link": { "type": "string", "description": "Photo page on Pexels." }, "large_image_link": { "type": "string", "description": "Image link about 1880 pixels wide." }, "original_image_link": { "type": "string", "description": "Original image link." }, "photographer_profile_link": { "type": [ "string", "null" ], "description": "Photographer Pexels profile link." } }, "additionalProperties": false }, "description": "Photos in Pexels search order." } }, "additionalProperties": false}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
pexels.com/search_photos- Returns
- photo description, photographer, image links, size, licence, photo page
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method pexels.com/search_photos with the inputs above.
Ask your agent
- Find me 30 free landscape-oriented stock photos of misty mountain lakes at sunrise for a website hero banner.
- I need portrait-format images of a barista pouring latte art, free to use commercially — show me who took each one and the licence.
- Pull page 3 of Pexels results for 'remote work home office' so I can see more options beyond what I've already browsed.
- Get square photos of fresh vegetables on a wooden table that I can use for Instagram posts, around 15 of them.
- Search Pexels for 'diverse team brainstorming whiteboard' photos, any orientation, and give me download links and image dimensions.
See more
All Pexels methodsFinds free stock videos on Pexels by search words, with creator, duration, preview image and a direct MP4 link, in Pexels search order starting at the chosen results page.
pexels.com/search_videosFinds Unsplash photos matching a search phrase, in search order, optionally by shape; excludes Unsplash+ photos unless included. Each result has image links, photographer, licence and photo page.
unsplash.com/search_photosFinds free-to-use Wikimedia Commons images for a topic in Commons relevance order. Each image comes with its links, creator and licence details.
commons.wikimedia.org/search_free_imagesFinds Pinterest pins for an idea in search order, with image, creator, board, saves and linked website. Limited to the first public search page.
pinterest.com/search_pinsSearches Open Food Facts packaged foods by name, optionally filtered by diet, country where sold and brand, ordered by popularity (most scanned first).
openfoodfacts.org/search_productsSearches PyPI by keywords and returns matching packages in relevance order, each with its latest version and that version's release date. Returns up to 100 results.
pypi.org/search_packagesSearches Apartments.com rentals by city, neighborhood, or ZIP code, with optional rent, bedroom, pet, and page filters. Rent and availability wording is returned when displayed; missing details are null.
apartments.com/search_apartmentsSearches B&H Photo products by keywords, with optional price range and sort order, and returns prices, savings, stock, ratings, identifiers, images and links in site order. Exact category names fall back to phrase matching to show products.
bhphotovideo.com/search_products
