Images

Search stock photos from Pexels and apply image fills.

Type reference

// Workflow: search → preview → place.
// Search returns slim photo objects: { id, alt, avg_color, width, height }.
// Preview returns the actual image so you can visually confirm before placing.
// To place: pass imageUrl:"pexel:<id>" to frames.create or frames.update.
// Attribution (photographer credit) is applied automatically as node description.
// User-provided image URLs also work — any public image URL can be used as imageUrl on frames.
// Powered by Pexels (pexels.com) — free stock photos. Requires PEXELS_API_KEY env var.

2 methods available.

search

read

Search photos by keyword via Pexels API

Parameter	Type	Required	Description
query	string	✓	Search keyword (e.g. "sunset", "office", "nature")
orientation	"landscape" | "portrait" | "square"	✗	Filter by photo orientation
size	"large" | "medium" | "small"	✗	Minimum photo size
color	string	✗	Filter by color — hex (e.g. '#FF0000') or named: red, orange, yellow, green, turquoise, blue, violet, pink, brown, black, gray, white
locale	string	✗	Locale for search (e.g. 'en-US', 'ja-JP'). Default: en-US
page	number	✗	Page number for pagination (default: 1)
per_page	number	✗	Results per page (default: 15, max: 80)

Response

Field	Type	Description
photos	array	[{ id, alt, avg_color, width, height }]
total_results	number	Total matching photos
page	number
per_page	number

preview

read

Preview a photo by ID — returns the image so you can see it before placing

Parameter	Type	Required	Description
id	number	✓	Photo ID from search results
size	"small" | "medium" | "large"	✗	Preview size (default: medium). small≈130px, medium≈350px, large≈940px height