Search photos by text
Search the photo library with natural language, not keywords. Pexafy understands the meaning, mood and story of a scene, so full descriptive sentences return far better matches than a couple of tags. For example:
- an old man sitting at a café table he has visited every morning for thirty years
- 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
Short queries like mountain sunset still work, but the more you describe the scene, light and emotion you have in mind, the closer the results.
You can combine your text query with filters (color, orientation, source, license, photographer, date) to narrow the results. At least one criterion is required: either a text query (q) or one of the filters.
What you get back
A list of photos in data. The most useful fields on each photo are:
| Field | Description |
|---|---|
| photo_id | Unique Pexafy identifier — use it with the Photos and Collections endpoints. |
| urls | Ready-to-use image links in five sizes: thumb, small, regular, large, full. |
| description / alt_description | A short caption and accessibility-friendly text. |
| color_name, color_hex, orientation | Visual attributes of the photo. |
| source, license_type | Where the photo comes from and how it may be used. |
| photographer_username, attribution | Credit information. attribution.html and attribution.plain are ready to display. |
| relevance_score | How closely the photo matches your query, from 0 to 1 (higher is better). |
Results are returned page by page — see the Pagination guide to fetch the next page.
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
Your search query in plain language — full descriptive sentences work best (e.g. two people sharing a bench in comfortable silence), though short queries like mountain sunset are fine too. Up to 500 characters. Optional if you provide at least one filter instead.
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). e.g. limit=4 with per_page=2 returns two pages of 2 results, then stops. 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.
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 guide.
Comma-separated list to return only the fields you need (e.g. photo_id,urls,attribution), which makes responses smaller. Omit to get every field your plan allows.
Valid values: photo_id, source_photo_id, image_url, urls, source_image_url, width, height, orientation, blur_hash, color_name, color_hex, source, license_type, photographer_username, photographer_full_name, photographer_url, source_description, description, alt_description, relevance_score, uploaded_on, attribution. There is no photographer field — the credit is carried by photographer_username, photographer_full_name and photographer_url. An unknown name returns 400 INVALID_FIELDS listing the values your plan accepts.
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.
Response
Successful Response
Changes
No recorded changes to this operation across all 1 revision of this API.