Search free stock photos
search_photosUse this when the user asks for a real photograph, or states a need that a photograph fills, and the picture is not already in the conversation.
Call it when they ask outright: “find me photos of…”, “show me images of…”, “I need a picture of…”, “do you have a photo of…”, “where can I find free photos of…”, in any language. Call it when they describe the need without asking to search: “I'm writing an article and need a header image”, “my landing page needs a hero image”, “I need something to illustrate this”. Call it when they ask for something meant to carry photographs: “write an article with pictures”, “a deck with images”. Call it when they name only the picture, with no reason given: “a photo of a white mug”, “a train in Japan”. If the user is working on something that usually carries photographs — an article, a page, a deck, a post — without asking for any, you may offer to look for some; call it only once they accept.
This covers requests for photographs for articles, blog posts, websites, landing pages, products, slides, documents, reports, social posts, ads, newsletters, banners, thumbnails, covers, posters, backgrounds, wallpapers and mood boards; photographs that illustrate a concept, explain a subject or accompany a piece of writing; and any request for free, stock, royalty-free, commercially usable, real or documentary photographs.
A request for a visual is not always a request for a photograph: this tool finds photographs that already exist — not illustrations, drawings, logos, icons, diagrams or screenshots — and it does not generate, edit or upscale an image, nor look for a named person.
It searches Pexafy's own index of millions of free-to-use photographs from stock libraries such as Unsplash, Pexels and Pixabay, matched to the scene described. Each result carries a rank, a photo_id, its licence, the credit line to display and an image link; the file itself comes from get_photo_file_by_photo_id. In a host that renders it, the grid shows them; the answer omits image links.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| english_search_sentence | Yes | Required. Describe the desired photograph in one concise English sentence, focusing on its visible subject and scene. Be specific: “Two colleagues laughing in a bright open-plan office” is more effective than “People office”. Keywords work too — send the user's own words, in English, rather than inventing detail they did not ask for. Maximum 250 characters. Describe one coherent scene, focusing on what should appear in the photograph rather than its intended use. Specify the requested photo shape or orientation in explicit_orientation_filter, not here. Example: “An old man sitting at a café table he has visited every morning for thirty years”. | |
| explicit_orientation_filter | No | Omit this parameter unless the user explicitly asks for a photo shape or orientation in their own words, or names a format whose shape is part of its definition — a vertical Short, a banner, a square post, a phone wallpaper. This is a hard filter, not a preference: it removes photos with other shapes before ranking, so using a shape the user did not request can exclude the best matches. Never infer the shape from a word inside `english_search_sentence` — “landscape” in “a natural landscape” names the scene, not the format — nor from the subject, the composition, or a purpose that fixes no shape (“a photo for my blog post”, “something for my landing page”). If you are choosing a value rather than repeating one explicitly requested by the user, omit it. Allowed values: `landscape`, `portrait`, `square`. Multiple values are allowed: two shapes return more than one alone, though any filter still returns less than none. For example, “anything but portrait” means `['landscape', 'square']`. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| error | No | ||
| budget | No | Present only when the caller is near the end of an allowance — the daily one without an account, the monthly one with. What is left of it, and, for a caller with no account, the one sentence that says what lifts the limit. Also carried by a refusal, where it describes the wall itself. | |
| notice | No | Why this answer is empty, when it is. A plan limit was reached: the allowance and when it returns. There is nothing to retry until then. | |
| success | No | ||
| presentation | No | Present only where the answer is drawn as the Pexafy grid: how it is shown. The grid is the complete visual answer; the reply needs no picture or link. |