canonical: https://jentic.com/apis/pexafy.com/pexafy

# Pexafy API

The Pexafy API searches free stock-photo libraries, among them Unsplash, Pexels, and Pixabay, by meaning rather than keywords and returns every photo in one response schema. A natural-language query or an uploaded reference image returns ranked matches, filtered by dominant colour name or hex, orientation, licence type, source, photographer, and publish date. Each photo carries its urls, dimensions, photographer, licence, and the attribution string to display, and saved collections and monthly, daily, and per-key usage counters round out the account side.

## For AI agents

Find free stock photos from Unsplash, Pexels, and Pixabay by natural-language description or by a reference image, with colour, orientation, licence, and photographer filters and ready-made attribution.

## Scope

Does not host your own uploads, edit or resize images, or license paid stock photos. Use for searching free stock photos and saving them to collections only.

## Capabilities

- Search stock photos with a full natural-language sentence ranked by meaning across Unsplash, Pexels, and Pixabay
- Find visually similar photos from an uploaded image or an existing photo_id, optionally steered with text
- Filter results by color_name or color_hex, orientation, license_type, source, photographer, and after_date
- Retrieve a photo's full details including width, height, source_image_url, and attribution
- Autocomplete photographer usernames and list a photographer's profiles across providers
- Save photos into named collections and remove them again
- Check this month's request usage, remaining quota, and usage per API key

## Use cases

### Agent picking a hero image through Jentic

An AI agent drafting a blog post or landing page needs an image that matches the mood of the text, not just a keyword. Through Jentic the agent searches for 'find a stock photo by description', loads the Pexafy photo search operation with its input schema, and passes a descriptive sentence in q with an orientation filter. The response includes urls and the attribution string, so the agent can insert the photo with its credit line, while your x-api-key stays with your own Jentic One instance.

Example prompt: Call GET `/api/v1/search/photos` with q='two people sharing a bench in a park at sunset', orientation=landscape, and per_page=5, then return the first photo's urls and attribution

### Finding alternatives to an existing image

Designers often have one photo that is almost right and want options with the same subject, composition, or colours. Pexafy accepts an uploaded image or a photo_id as the reference, and an optional q plus text_alpha balances words against the picture. The similar-photos operation returns lookalikes for a photo already in the library, never including the reference itself.

Example prompt: Call GET `/api/v1/photos/{photo_id}/similar` with the chosen photo_id and per_page=10, then list the photographer and source for each result

### Brand-consistent image sets

Marketing teams building a campaign want photos that share a palette and licence terms. The colours facet lists the color_name values search accepts, color_hex with color_tolerance keeps results near a brand colour, and license_type and source filters keep only photos that can be used in a given way.

Example prompt: Call GET `/api/v1/facets/licenses`, then GET `/api/v1/search/photos` with q='minimal office workspace', color_hex='#1E90FF', color_tolerance=30, and license_type=free

### Moodboards with saved collections

A creative agent gathers candidates into a collection that a person can review later. Creating a collection needs only a name, adding a photo needs its photo_id, and a duplicate add returns a 409. Removing the cover photo promotes the most recently added remaining photo to cover.

Example prompt: Call POST `/api/v1/collections` with name='Autumn campaign', then POST `/api/v1/collections/{collection_id}/photos` with a photo_id from a search result

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/search/photos` | Search photos with natural language |
| POST | `/api/v1/search/photos` | Search photos by reference image |
| GET | `/api/v1/photos/{photo_id}` | Get a photo's full details |
| GET | `/api/v1/photos/{photo_id}/similar` | Get visually similar photos |
| GET | `/api/v1/facets/sources` | List photo providers |
| POST | `/api/v1/collections` | Create a collection |
| POST | `/api/v1/collections/{collection_id}/photos` | Add a photo to a collection |
| GET | `/api/v1/usage` | Get this month's request usage |

## Key resources

- **Photos** — Search results and photo details with urls, dimensions, dominant colours, photographer, licence, and attribution
- **Facets** — Lists of colours, sources, orientations, licences, and photographers that the search filters accept
- **Collections** — Named albums of saved photos with a description, photos_count, and cover_photo_id
- **Usage** — Monthly, daily, and per-key request counters with used, limit, and remaining

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 65 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 99 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 46 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 91 / 100
- **View full report:** https://jentic.com/apis/pexafy.com/pexafy/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Pexafy by hand means creating an API key, sending it in the x-api-key header, and handling cursor pagination through pagination.next_cursor and multipart uploads for image search. Through Jentic you install once, import Pexafy from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Pexafy puts the collection id in the URL path (`/api/v1/collections/{collection_id}/photos`), so a rule can pin your agent to one collection while it searches freely. You choose the operations it may call, so destructive ones like deleting a collection or removing photos are not included unless you add them.
- **Credential handling:** Your Pexafy API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find a stock photo by description' or 'find similar images', and Jentic returns the matching Pexafy operation with its input schema, including the colour, orientation, and licence filters, so the agent calls it without browsing the reference docs.

## Related APIs

- **Pexels Image & Video API** — Direct keyword search of the Pexels photo and video library
- **Pixabay** — Keyword search over Pixabay's free images and videos
- **Cloudinary Upload API** — Upload and transform chosen images for delivery on your own site

## FAQ

### What authentication does the Pexafy API use?

The Pexafy API authenticates with an API key sent in the x-api-key header (ApiKeyAuth) per its OpenAPI spec. Keys are issued from the Pexafy dashboard without an application review. Through Jentic the key is stored by your own instance and attached at call time, so the agent never handles it.

### Can I search the Pexafy API with an image instead of text?

Yes. POST `/api/v1/search/photos` takes an uploaded image file, or a photo_id query parameter for a photo already in the library, and returns visually similar photos. You can add words in q to steer the match and set text_alpha to balance the text against the image.

### What are the rate limits for the Pexafy API?

The OpenAPI spec does not state numeric limits; quotas depend on your plan, listed at https://pexafy.com/pricing/. The GET `/api/v1/usage` operation reports used, limit, and remaining requests for the current billing month, so an agent can check its headroom before a large batch.

### Is there a Pexafy MCP server?

Yes - per its OpenAPI spec description, Pexafy also exposes an MCP server for LLM clients. You can also connect the Pexafy API directly through Jentic: your agent gets the full 20-endpoint surface from the spec without loading another server's tool definitions into its context, your key is injected at call time by your self-hosted instance instead of living in an MCP config, and your rules decide which operations the agent may call.

### How do I find a stock photo by description through Jentic?

Search Jentic for 'find a stock photo by description', load the GET `/api/v1/search/photos` operation, and execute it with a descriptive sentence in q plus any filters such as orientation or source. Each result includes urls and an attribution string to display. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Pexafy API?

Yes. Write a rule that allows the photo search and photo detail operations plus adding photos under one collection id, and the agent can find images and save them to that moodboard while deleting collections stays out of reach. Every call it makes is logged for review.