Knowledge & tools

Stock photo & video tools

Three tools for finding media to use in content - hero images, illustrations, video clips. All return free photos with a ready-to-use image URL; Pexels and Pixabay find videos too, with direct MP4 links. The agent supplies the query and picks the action and filters per call; you just enter an API key.

Pexels (pexels) - search the Pexels library for photos and videos; videos come with direct MP4 download links, ready for Reels/clips. Requires a free Pexels API key.
Pixabay (pixabay) - search the Pixabay library for images (photos, illustrations, vectors) and videos, under the Pixabay Content License (commercial use, no attribution required). Requires a free Pixabay API key.
Unsplash (unsplash) - search the Unsplash photo library. Requires a free Unsplash Access Key (paste the key; the Client-ID prefix is handled for you).

What you get back

Photo results share the same core shape on all three tools - for each match: a direct image_url (display size), the photo's page_url, the photographer and their photographer_url (for attribution), and width/height. Pexels and Unsplash photos also come with portrait_url (a tall crop for vertical formats), original_url (the full-resolution file), and the dominant color - Unsplash adds a story_url (1080×1920) crop on top. Pixabay instead adds webformat_url (a 640px preview), type, and is_ai_generated.

{ "total": 8000,
  "results": [ { "id": "...", "description": "...", "photographer": "...", "photographer_url": "...",
                 "page_url": "...", "image_url": "...", "portrait_url": "...", "original_url": "...",
                 "width": 6000, "height": 4000, "color": "#6F8E91" } ] }

image_url is ready to use (Pexels src.large / Pixabay 1280px / Unsplash 1080px). Tip: query should describe the visual (e.g. "person reviewing documents at a desk"), not the article topic.

Pexels

Configuration is a single field - your Pexels API key, sent in the Authorization header, stored encrypted and never shown again. One key covers photos and videos; there are no other settings - everything below is a parameter the agent sets per call.

Get a key: go to pexels.com/api → sign in → Get Started / Your API Key (accept the API terms) → copy the key. Free tier: 200 requests/hour, 20,000/month, no card.

Actions (5)

All read-only. The agent picks the action per call:

Action	Required	Optional	Returns
`search_photos`	`query`	`per_page` (≤80), `page`, `orientation`, `color`, `size`	`{ total, results:[photo] }` (shape above)
`get_photo`	`id`	-	one photo object
`search_videos`	`query`	`per_page`, `page`, `orientation`, `size`	`{ total, results:[video] }` (shape below)
`popular_videos`	-	`per_page`, `page`, `min_width`, `min_height`, `min_duration`, `max_duration`	`{ total, results:[video] }`
`get_video`	`id`	-	one video object

Each video result has the usual metadata plus a video_files list of downloadable renditions - link is a direct MP4 download URL:

{ "total": 4000,
  "results": [ { "id": "...", "page_url": "...", "thumbnail": "...", "duration_seconds": 14,
                 "width": 3840, "height": 2160, "videographer": "...", "videographer_url": "...",
                 "video_files": [ { "quality": "hd", "file_type": "video/mp4",
                                    "width": 1920, "height": 1080, "fps": 30,
                                    "link": "https://videos.pexels.com/..." } ] } ] }

Parameter notes

query - describe the visual subject.
per_page - 1–80 (default 10).
page - ≥1 (pagination).
orientation - landscape / portrait / square.
color (photos only) - red, orange, yellow, green, turquoise, blue, violet, pink, brown, black, gray, white.
size - a minimum-resolution floor, not a rendition pick. Photos: large = 24MP, medium = 12MP, small = 4MP. Videos: large = 4K, medium = Full HD, small = HD.
min_width / min_height / min_duration / max_duration (popular_videos) - dimension floors in pixels, duration bounds in seconds.

Choosing renditions

Photos: use image_url for articles and previews; portrait_url for vertical formats (Stories, Reels covers); original_url only when full resolution is needed.
Videos: pick the video_files entry by resolution - quality is hd or sd, and each entry lists width/height/fps. For Reels/clips, a portrait-orientation search plus the entry closest to 1080×1920 is usually right; link downloads the MP4 directly.

Pixabay

Configuration is a single field - your Pixabay API key, sent as the key query parameter, stored encrypted and never shown again.

Get a key: create a free account at pixabay.com → open pixabay.com/api/docs while logged in → your key is shown inline in the Search Images parameter table. Free tier: 100 requests per minute, no card.

Actions (4)

All read-only. Two things make Pixabay a little different: the query is optional - leave it out to browse popular content - and the by-id lookups are the same endpoints filtered by id, not separate routes.

Action	Required	Optional	Returns
`search_images`	-	`query`, `image_type`, `orientation`, `category`, `colors`, `min_width`, `min_height`, `editors_choice`, `safesearch`, `order`, `lang`, `page`, `per_page` (3–200)	`{ total, results:[image] }` (shape above)
`get_image`	`id`	-	one image object
`search_videos`	-	`query`, `video_type`, `category`, `min_width`, `min_height`, `editors_choice`, `safesearch`, `order`, `lang`, `page`, `per_page`	`{ total, results:[video] }` (shape below)
`get_video`	`id`	-	one video object

Video results look like this - link is a direct CDN MP4:

{ "total": 500,
  "results": [ { "id": "...", "description": "...", "page_url": "...", "thumbnail": "...",
                 "duration_seconds": 21, "videographer": "...", "videographer_url": "...",
                 "type": "film", "is_ai_generated": false,
                 "video_files": [ { "quality": "medium", "width": 1920, "height": 1080,
                                    "link": "https://cdn.pixabay.com/..." } ] } ] }

Parameter notes

query - optional; omit it to browse popular content.
image_type - all / photo / illustration / vector; video_type - all / film / animation.
orientation (images only) - all / horizontal / vertical. Videos have no orientation filter - spot vertical clips by height > width on the returned dimensions.
category - one of Pixabay's 20 content categories (nature, business, people, ...).
colors (images only) - comma-separated, so multiple at once.
min_width / min_height - pixel floors.
editors_choice / safesearch - curation and safety toggles.
per_page - 3–200 (note the minimum of 3).

Choosing renditions

Images: image_url is the 1280px version - standard keys top out there (Pixabay's 1920px/original tier needs their "full API access" approval). webformat_url is a 640px preview whose link expires after ~24 hours - fine for a quick look, not for publishing.
Videos: video_files has quality tiers large / medium / small / tiny, each with width/height. large (up to 4K) isn't always available and is omitted when empty - fall back to medium.

Unsplash

Configuration is a single field - your Unsplash Access Key, stored encrypted and never shown again. Paste just the key; Hania adds the required Client-ID prefix automatically (a value that already includes it isn't doubled).

Get a key: go to unsplash.com/oauth/applications → sign in → New Application (accept the API guidelines, name it) → copy the Access Key (not the Secret key). Free "Demo" tier: 50 requests/hour; "Production" approval raises it.

Actions (3)

Action	Required	Optional	Returns
`search_photos`	`query`	`per_page` (≤30), `page`, `orientation`, `color`, `order_by`, `content_filter`	`{ total, results:[photo] }` (shape above)
`get_photo`	`id`	-	one photo object, and registers the use with Unsplash
`random_photo`	-	`query`, `orientation`, `content_filter`, `count` (1–10)	`{ total, results:[photo] }`

The convention to follow: search, then get_photo the one you pick. Beyond returning full details, get_photo registers the use with Unsplash - their required download tracking - so it should be called for the photo that actually gets used, not for browsing.

Parameter notes

query - describe the visual subject (optional on random_photo).
per_page - 1–30 (default 10).
page - ≥1 (pagination).
orientation - landscape / portrait / squarish.
color - black_and_white, black, white, yellow, orange, red, purple, magenta, green, teal, blue.
order_by - relevant (default) / latest.
content_filter - low (default) / high.
count (random_photo) - how many random picks, 1–10.

Choosing renditions

image_url (1080w) for articles and previews; portrait_url (1080×1350) for portrait feed posts; story_url (1080×1920) for Stories and Reels covers; original_url only when full resolution is needed.
The crop URLs are generated on demand by Unsplash's CDN, and hotlinking them is exactly what Unsplash wants - don't download and re-host.

Choosing filters & library

orientation - landscape for hero/banner images, portrait for sidebars, square/squarish for thumbnails (Pixabay calls these horizontal/vertical).
color - match a brand or article theme (e.g. blue, black_and_white); on Pixabay the parameter is colors and takes several at once.
Unsplash also offers order_by (latest for fresh imagery) and content_filter (high for stricter safety).

Which library? All three are good for photos. Unsplash skews toward editorial/lifestyle photography and adds sort + safety filters and a random pick; Pexels and Pixabay both do video; Pixabay is the one with illustrations and vectors, category/multi-color filters, an is_ai_generated flag, and no-query browsing of popular content. A bot can have any mix - with more than one, the agent tries the most suitable library per topic (or falls back to another if the first returns nothing).

Attribution

All three libraries are free for commercial use, and the photographer/videographer name, their profile URL, and page_url are provided for credits - but the rules differ. Unsplash requires attribution: credit the photographer and Unsplash wherever the photo is used. Pexels doesn't require it but asks for a prominent link back and a credit "when possible". Pixabay's Content License requires nothing, though its API terms ask that you show where results come from wherever they're displayed.

Hosting rules differ too. Pixabay image URLs are meant for temporary display - its terms allow caching them for up to 24 hours and don't permit mass downloads, so publishing flows should fetch and re-host the file (Hania's publishing flows already do this); Pixabay videos can be embedded directly. Unsplash is the opposite: hotlink its CDN URLs rather than re-hosting.

Behaviors & gotchas

Unsplash key is the Access Key, pasted raw - the Client-ID prefix is added in code (idempotent).
Pexels is lenient - a bad key returns HTTP 200 with empty results (photo and video endpoints alike), never an auth error. So if searches consistently come back empty, re-check the key before blaming the query.
Omitted action defaults to search_photos - configs and prompts from before video support keep working as-is.
Pixabay fails loudly - the opposite of Pexels. A bad key is a plain HTTP 400 ("Invalid or missing API key"), a nonexistent id 400s too ("Image #N does not exist"), and hitting the rate limit returns a 429 ("API rate limit exceeded").
Pixabay's total is capped - it's the API-accessible count, at most 500 per query, not the full library count.
Unsplash validates filters - an invalid color/orientation returns a 400; the schema's enum constraints keep the agent from sending bad values. A bad key is a 401/403, and a 403 with rate-limit wording means the 50/hour Demo ceiling.

Costs & limits

Pexels free tier: 200 requests/hour, 20,000 requests/month (photo and video calls share the quota); hitting the quota returns a 429 - wait for the window to reset. Pixabay: 100 requests per minute per key, and standard keys top out at 1280px images. Unsplash Demo tier is 50 requests/hour (Production approval raises it). Per-query options are chosen by the agent automatically.

Classification & lifecycle

All three are read-only, so the destructive / sends-data-externally classification flags don't apply (they ship unset). Each is post-call-hook eligible.

Migration: these replace the older "Pexels – Search Photos" / "Unsplash – Search Images" API-Call presets; existing credentials carry over automatically - no re-entry needed.