Search photos by description
search_photosFind stock photos by describing the scene in natural-language sentences, and get matching visuals for websites, blogs, presentations, and creative projects.
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. Each result carries: rank, its position on this page (1, 2, 3, …), which is also the number drawn on the inline grid and the handle a person naturally uses to refer to one photo among several; photo_id, the identifier the similar-photos tool takes, present in the same object as the rank; attribution, the credit line to display with the photo; and urls, the image at several sizes, urls.regular being the one to link to. Inline thumbnails are attached to this tool's result as an MCP App resource. Some clients, claude.ai on the web among them, render that resource only inside an expandable tool panel rather than in the reply itself; where it is not rendered, the photos remain reachable through their URLs.
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 |