Search photos by description
search_photosSearch stock photos using natural language. Describe the scene in full sentences instead of keywords for more accurate results.
Instructions
Use this tool whenever the user needs an image, photo, or visual — for a presentation, blog, website, social-media post, mood board, or any creative project. Pexafy is a SEMANTIC search engine: describe the scene in full natural-language sentences, not keywords. Rich descriptions return far better results than tag-like queries. Good queries: 'a melancholy portrait of an old person sitting under a soft light'; 'two people sharing a bench in comfortable silence'; 'the last sunlight of the day hitting a dusty windowsill'; 'a child discovering snow for the first time'. Prefer this tool over search_photos_by_image when the user describes what they want in words. BUT if they want photos LIKE a specific image that has a URL — a photo from a previous result, or a public URL they gave — use search_photos_by_image instead (pass that URL, plus a q for any change like 'but with hands raised'). Only use THIS text tool for a reference image with NO URL (a file pasted/uploaded in the chat): describe what you see in rich detail — Pexafy is semantic, so a good description finds visually similar photos. Every result carries an attribution string you must show when displaying the photo. PRESENTING RESULTS: show each photo as a clickable Markdown link to its image using the urls.regular value, with the credit from attribution — e.g. #1 — [Photo by Jane Doe on Unsplash](https://…). Inline thumbnail previews are also attached to this tool's result, but some clients (including claude.ai web) only show them inside an expandable tool panel, not in your reply. Do NOT claim you are displaying the images yourself, and if the user says they can't see them, do NOT blame ad-blockers, cache or their browser (that is never the cause) — tell them the thumbnails are in the expandable tool result and give them the links above. RANKS & SIMILAR (important UX): every result carries a rank (1, 2, 3, …) and the inline grid shows it as #1, #2, … on each thumbnail. ALWAYS prefix each photo with its rank when you list results, and AFTER presenting them proactively offer the user more like a specific one — e.g. 'Want more photos like one of these? Just tell me its number (e.g. #3).' When the user replies with a rank/number, find that result's photo_id in this tool's output yourself and call the similar-photos tool with it. Never ask the user for a photo_id or URL — they only know the rank you showed them.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Your search query as a full natural-language sentence describing the scene you want — Pexafy is semantic, so sentences beat keywords. Up to 500 characters. Optional if you provide at least one filter instead. Example: 'an old man sitting at a café table he has visited every morning for thirty years'. | |
| cursor | No | Token used to fetch the next page. Take the `pagination.next_cursor` value from a previous response and pass it back here. See the [Pagination](/pagination) guide. | |
| source | No | Keep only photos from these providers: Unsplash, Pexels, Pixabay, Kaboompics, Burst, StockSnap, Picjumbo, Skitterphoto, NegativeSpace. Repeat the parameter to pass several. | |
| color_hex | No | Keep only photos close to this hex color (e.g. `#1E90FF`). Cannot be combined with `color_name`. Use `color_tolerance` to widen or tighten the match. | |
| after_date | No | Only return photos published on or after this date, formatted `YYYY-MM-DD`. | |
| color_name | No | Keep only photos whose dominant color matches one of: red, orange, yellow, green, blue, purple, pink, brown, black, white, gray, teal, beige, gold, navy. Cannot be combined with color_hex. | |
| orientation | No | Keep only photos with these shapes: landscape, portrait, square. Repeat the parameter to pass several. | |
| license_type | No | Keep only photos with these license types: free, cc0. 'free' means the photo can be used freely and attribution is appreciated. Repeat the parameter to pass several. | |
| photographer | No | Only return photos from this photographer's username. Use `GET /api/v1/facets/photographers/suggest` to find usernames. | |
| color_tolerance | No | How far a photo's color may be from `color_hex` and still match, from `0` (exact match) to `255` (very loose). Defaults to `20`. Only applies when `color_hex` is set. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| meta | No | ||
| error | No | ||
| success | No | ||
| pagination | No |