search_images
Search Pexels stock photos by subject queries and retrieve hotlinkable image URLs with multiple sizes, color, and photographer attribution for landing page image slots.
Instructions
Searches Pexels stock photos (see https://www.pexels.com/api/) by short English subject queries. Returns hotlinkable URLs at several sizes, avg_color for matching section backgrounds, plus photographer name and attribution URL. PICK BY SIZE, NOT JUST TOPIC: each photo carries a sizes map (delivered WxH px per variant) and the response includes a size_guide — match the variant width to the slot's rendered width (hero/banner → src.large ~940px or src.large2x ~1880px retina; card/thumb → src.medium ~350px; avatar → src.tiny), because a too-small variant stretched across a big slot pixelates ('vỡ ảnh') and src.original / an oversized variant in a small card bloats the page ('nặng trang'). BATCH MODE: pass queries: [...] to fetch multiple subjects in PARALLEL — e.g. ['fresh coffee cup','barista pouring','interior cafe'] for hero + about + gallery — returns { queries: { [q]: result } } so the caller picks one image per slot in a single round-trip; default pick='best' returns only the top photo per query (compact, drop-in for specials.src), pick='all' returns the full list. query (single) returns the full result like before. Works out of the box via a shared hosted proxy; set PEXELS_API_KEY env or x-pexels-key header to use your own quota. ONLY for image slots with NO source image: when the user supplied images or the reference HTML/URL contains image URLs (ingest AST images/background_images/og_image), re-host THOSE via upload_images instead of searching stock photos.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Result page for pagination (default 1). | |
| pick | No | With `queries`, 'best' (default) returns only the top photo per query (compact, drop-in for specials.src); 'all' returns the full result. Single-query calls always return the full result. | |
| size | No | Minimum photo size to return (default any). | |
| color | No | Optional color filter: a name (red, blue, …) or a hex like '6a8f3c'. | |
| query | No | Single subject query — backward-compat. Prefer `queries` when the page needs 2+ images. | |
| queries | No | Multiple subject queries (one per image slot) to run in parallel — recommended for a page with 2+ images so each only costs ONE round-trip. | |
| per_page | No | Photos per query (default 5). | |
| orientation | No | Preferred shape — 'landscape' for heroes/banners, 'portrait' for tall cards, 'square' for icons/avatars. |