Search photos by image
Upload an image and get visually similar photos in return — same subject, composition, colors or style. Ideal for finding alternatives to a photo you already have.
You can also pass a text query (q) together with the image to steer the results: the search then balances what the image looks like with what your words describe. Use text_alpha to control that balance.
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.
Authorizations
Pass your Pexafy API key in this header.
Get your API key at pexafy.com/dashboard/api-keys/create.
Query Parameters
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.
500Balance 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.
0 <= x <= 10Keep 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.
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.
0 <= x <= 255Keep 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.
1 <= x <= 100Maximum TOTAL number of results to return across all pages — NOT the page size (use per_page for that). Omit for no cap.
1 <= x <= 100Minimum 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.
0 <= x <= 1Only 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).
relevance, newest 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.
Body
Image file (JPEG, PNG, WebP, or AVIF)