Skip to main content

pexafy-python

Python client for the Pexafy Stock Photos API. Search a catalogue of free stock photos by describing what you want, or by handing it an image to match.

pip install pexafy

Getting started

from pexafy import Client

client = Client("your-api-key")

for photo in client.search("a quiet street in the rain", per_page=5):
    print(photo.urls.regular, "-", photo.alt_text)

The key comes from your dashboard; the free tier does not ask for a card. If you would rather not put it in the code, the client picks up PEXAFY_API_KEY from the environment.

Writing queries

Search runs on meaning, not keywords, so full sentences work better than a pile of nouns. two people hiking on a ridge at dawn finds what you would expect; hiking dawn people gives you a worse ranking, because you have thrown away the relationships between the words.

Filters narrow the result set after the semantic match:

result = client.search(
    "an empty office at night",
    orientation="landscape",
    color_name="blue",
    source=["Pexels", "Unsplash"],
    per_page=20,
)

print(len(result), "photos in", result.took_ms, "ms")

orientation, source and license_type take several values, as a list or as a comma separated string. color_name takes one: the API filters on a single colour, and passing more raises rather than quietly filtering on whichever one arrived last.

Paging

A single call returns one page. iter_search follows the cursor for you and yields photos until the results run out or you have seen enough:

for photo in client.iter_search("vintage typewriter", max_results=200):
    download(photo.urls.large)

Search by image

Pass a path, raw bytes, or an open file:

similar = client.search_by_image("moodboard/reference.jpg", per_page=12)

If you already have a photo id, client.similar(photo_id) is cheaper — the image does not have to be uploaded and encoded again.

Async

The same surface, awaitable:

import asyncio
from pexafy import AsyncClient

async def main():
    async with AsyncClient() as client:
        pages = await asyncio.gather(
            client.search("desert road"),
            client.search("snow covered pines"),
        )
    for page in pages:
        print(len(page))

asyncio.run(main())

Errors

Everything raised inherits from PexafyError. The ones worth catching separately:

from pexafy import errors

try:
    client.search("...")
except errors.RateLimitError as exc:
    time.sleep(exc.retry_after or 60)
except errors.AuthenticationError:
    ...          # key is missing, malformed or revoked
except errors.APIError as exc:
    print(exc.status_code, exc.code, exc.request_id)

request_id is worth logging. It is the fastest way to get an answer if you need to ask about a specific call.

Timeouts and 5xx responses are retried twice with backoff, and Retry-After is honoured when the server sends it. Set max_retries=0 if you would rather handle that yourself.

Command line

$ pexafy search "morning fog over pine trees" -n 3
0.847  019e0eb8-b028-73cb-9296-dfa70f557bc9   4000x2667   green      Pexels     https://...
0.812  019e4c9b-3022-7660-b43d-e730b8435f24   6000x4000   green      Unsplash   https://...
0.798  019e4f39-66d4-7ef2-bc9b-eb5340fd243e   3648x5472   grey       Pexels     https://...

pexafy photo <id>, pexafy similar <id> and pexafy usage are also there. Add --json to any of them for the raw response.

Attribution

Photos come from several providers with different licence terms. Every photo carries an attribution object with a ready made credit line:

photo.attribution.plain   # Photo by J. Doe
photo.attribution.html    # <a href="...">J. Doe</a>

Check photo.license_type if your use depends on it.

Reference

Method What it does
search(q, **filters) one page of results
iter_search(q, max_results=None, **filters) every page, cursor handled
search_by_image(image, **filters) match an image you supply
get_photo(photo_id, fields=None) one photo by id
similar(photo_id, **filters) photos close to an existing one
colors() sources() orientations() licenses() filter values you can use
suggest_photographers(q) photographer(username) photographer lookup
collections() create_collection(name) collection(id) delete_collection(id) saved sets
add_to_collection(id, photo_id) remove_from_collection(id, photo_id) photos in a set
usage() usage_daily(days=None) usage_monthly(months=None) usage_by_key() where you are against your quota

AsyncClient has every one of these methods, awaitable. Full API documentation is at docs.pexafy.com; the limits of each plan are at docs.pexafy.com/plans.

Versioning

The package follows semantic versioning. Within 1.x, an upgrade does not break code written against 1.0: methods and their parameters stay, and new ones are added alongside. Every change is listed in the changelog.

Requirements

Python 3.9 or newer. The only dependency is httpx.

Licence

MIT.

Metadata

Release files for pexafy 1.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pexafy 1.0.1
File Size Uploaded Provenance Actions
pexafy-1.0.1.tar.gz 19.9 kB With provenance Details for pexafy-1.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pexafy 1.0.1
File Interpreter ABI Platform Actions
pexafy-1.0.1-py3-none-any.whl Python 3 none any Details for pexafy-1.0.1-py3-none-any.whl

Total release size: 35.0 kB

Release files / pexafy-1.0.1.tar.gz

Download URL pexafy-1.0.1.tar.gz
Size 19.9 kB
Tags Source
SHA-256 checksum
How to use checksums
3e51efcc452c16d25067c5fc81b954d77edaabd5724f47609cb8984473e78a91
BLAKE2b-256 checksum
How to use checksums
e86b4afd163d97f89dc2f13a2a7c207271c520d31d02e1ebce9569ed54f9796e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / pexafy-1.0.1-py3-none-any.whl

Download URL pexafy-1.0.1-py3-none-any.whl
Size 15.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ebe8752bdf85d6c35bf698e0842472911dcb552b95974443d6207d87cc969e3f
BLAKE2b-256 checksum
How to use checksums
107e1738ae374e279831e207f5537bc01697e9629831e067a92bd6dcdbfbd841
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for pexafy 1.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pexafy-1.0.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page