POST
Search photos by image

Authorizations

x-api-key
string
header
required

Pass your Pexafy API key in this header.

Get your API key at pexafy.com/dashboard/api-keys/create.

Query Parameters

q
string | null

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.

Maximum string length: 500
text_alpha
number | null

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.

Required range: 0 <= x <= 10
color_name
string | null

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.

color_hex
string | null

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.

color_tolerance
integer | null

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.

Required range: 0 <= x <= 255
orientation
string[] | null

Keep only photos with these shapes: landscape, portrait and/or square. Repeat the parameter to pass several. See GET /api/v1/facets/orientations.

source
string[] | null

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.

license_type
string[] | null

Keep only photos with these license types (e.g. free). Call GET /api/v1/facets/licenses to list the available license types.

per_page
integer
default:20

Number of photos per page, from 1 to 100. Defaults to 20.

Required range: 1 <= x <= 100
limit
integer | null

Maximum TOTAL number of results to return across all pages — NOT the page size (use per_page for that). Omit for no cap.

Required range: 1 <= x <= 100
score_threshold
number | null

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.

Required range: 0 <= x <= 1
after_date
string | null

Only return photos published on or after this date, formatted YYYY-MM-DD.

sort_by
enum<string> | null

Order of the results: relevance (default — best match first) or newest (most recently added first).

Available options:
relevance,
newest
photographer
string | null

Only return photos from this photographer's username. Use GET /api/v1/facets/photographers/suggest to find usernames.

cursor
string | null

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

multipart/form-data
image
file
required

Image file (JPEG, PNG, WebP, or AVIF)

Response

Successful Response

success
boolean
data
object[]
meta
object
error
object | null
pagination
object | null