Search photos by image
Give the search a picture and get visually similar photos in return — same subject, composition, colors or style. Ideal for finding alternatives to a photo you already have.
The picture can come from either side: upload a file (image), or name a photo you already found here with photo_id — never both. With a photo_id nothing is uploaded and nothing is analysed again, so it answers faster; the photo itself is left out of its own results. On its own, photo_id returns exactly what Find similar photos returns for that photo.
You can also pass a text query (q) together with the picture to steer the results: the search then balances what the picture looks like with what your words describe. Use text_alpha to control that balance. That is how you keep what someone asked for while showing more of the photo they picked: photo_id for the photo, q for the intent.
Accepted formats: JPEG, PNG, WebP or AVIF, up to 10 MB.
The same filters as text search are available, and the response has the exact same shape — see Search photos by text for the list of fields you get back.
Request
- Base URL: https://api.pexafy.com
- URL: https://api.pexafy.com/api/v1/search/photos
- Auth: API key in header x-api-key
Query parameters
A photo already in the catalogue, used as the reference instead of an upload. Mutually exclusive with image. Nothing is uploaded and nothing is analysed again, and the photo itself never appears among its own results. On its own it returns exactly what GET /api/v1/photos/{photo_id}/similar returns; combined with q, it returns that same search steered by your words. Per-plan caps on similar photos apply to it as well.
Optional words, in plain language, to steer the visual match (e.g. the same scene but at golden hour or warmer and more cheerful). When set, results match both the picture and your text.
Balance between your text and the image when both are provided, from 0 to 10. 0 ignores the text (pure visual search), 1.7 (the default) is balanced, and higher values give your words more weight. Has no effect without q.
Keep only photos whose dominant color matches this name (e.g. blue, red, teal). Call GET /api/v1/facets/colors (see the Facets section) to get the list of available color names. Cannot be combined with color_hex.
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.
How far a photo's colour may sit from the one you asked for, from 0 (strict) to 255 (very loose). Defaults to 20. Applies to both color_hex and color_name: for a hex it is the radius around that exact shade, for a name it widens or narrows the colour family. The published spec used to say it applied to color_hex only, which was never true of the code.
How far a photo's colour may sit from the one you asked for, from 0 (strict) to 255 (very loose). Defaults to 20. Applies to both color_hex and color_name: for a hex it is the radius around that exact shade, for a name it widens or narrows the colour family.
Keep only photos with these shapes: landscape, portrait and/or square. Repeat the parameter to pass several. See GET /api/v1/facets/orientations.
Keep only photos from these providers (e.g. Pexels, Unsplash, Pixabay). Repeat the parameter to pass several. Call GET /api/v1/facets/sources to list every available source.
Keep only photos with these license types (e.g. free). Call GET /api/v1/facets/licenses to list the available license types.
Number of photos per page, from 1 to 100. Defaults to 20.
Maximum TOTAL number of results to return across all pages — NOT the page size (use per_page for that). Omit for no cap.
Minimum relevance a photo must reach to appear, from 0 to 1. Raise it (e.g. 0.3) to keep only strong matches and drop loosely related photos; leave it unset to get the widest set of results.
Only return photos published on or after this date, formatted YYYY-MM-DD.
Order of the results: relevance (default — best match first) or newest (most recently added first).
Only return photos from this photographer's username. Use GET /api/v1/facets/photographers/suggest to find usernames.
Token to fetch the next page. Take pagination.next_cursor from a previous response and pass it back here — no need to re-upload the image. See the Pagination guide.
Response
Successful Response
Changes
No recorded changes to this operation across all 1 revision of this API.