Stock-photo search tools

Two tools for finding images to use in content — hero images, illustrations. Both return free, attribution-friendly photos with a ready-to-use image URL. The agent supplies the query and chooses filters per call; you just enter an API key.

• Pexels (pexels) — search the Pexels library. Requires a free Pexels API key.
• Unsplash (unsplash) — search the Unsplash library. Requires a free Unsplash Access Key (paste the key; the Client-ID prefix is handled for you).

What you get back

Both tools return the same projected shape — for each match: a direct image_url (display size), the photo's page_url, the photographer and their photographer_url (for attribution), width/height, and the dominant color.

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

image_url is ready to use (Pexels src.large / Unsplash urls.regular). 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.

Get a key: go to pexels.com/api → sign in → Get Started / Your API Key (accept the API terms) → copy the key. Free tier: a generous monthly limit, no card.

One action — search — with these parameters (the agent sets them):

• query (required) — describe the visual subject.
• per_page — 1–80 (default 10).
• page — ≥1 (pagination).
• orientation — landscape / portrait / square.
• color — red, orange, yellow, green, turquoise, blue, violet, pink, brown, black, gray, white.

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.

One action — search — with these parameters:

• query (required) — describe the visual subject.
• 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.

Choosing filters & library

• orientation — landscape for hero/banner images, portrait for sidebars, square/squarish for thumbnails.
• color — match a brand or article theme (e.g. blue, black_and_white).
• Unsplash also offers order_by (latest for fresh imagery) and content_filter (high for stricter safety).

Pexels vs Unsplash: both are good. Unsplash skews toward editorial/lifestyle photography and adds sort + safety filters; Pexels has a larger per_page cap. A bot can have one or both — with both, the agent tries the more suitable library per topic (or falls back to the other if the first returns nothing).

Attribution

Both libraries are free for commercial use without required attribution, but crediting the photographer is good practice — the photographer, photographer_url, and page_url fields are provided for that. (Unsplash's API guidelines appreciate a link back to the photo and photographer.)

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 or invalid filter returns HTTP 200 with an empty/partial result rather than an auth error, so treat an empty results[] as "no matches or bad key."
• Unsplash validates filters — an invalid color/orientation returns a 400; the schema's enum constraints keep the agent from sending bad values.

Costs & limits

Pexels free tier has a generous monthly limit; Unsplash Demo tier is 50 requests/hour (Production approval raises it). Per-query options are chosen by the agent automatically.

Classification & lifecycle

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