Unsplash Photo API
Community OpenAPI document · agent-readyMediaContent DeliveryapiKey3 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Search the Unsplash library by keyword, retrieve a photo by id, or fetch random photos, with filters for orientation, color, and content safety. Returns image URLs and metadata for headers, galleries, and backgrounds.
Use for: Find high-resolution photos of mountains, Search for landscape-orientation images of a city, Get a random nature photo for a header image, Retrieve the details of a specific Unsplash photo
Not supported: Does not upload, edit, or license photos, and does not process image files. Use for searching and retrieving Unsplash photos only.
The Unsplash Photo API searches and retrieves photos from the Unsplash library and returns each with its URLs and metadata. It exposes a keyword search operation with pagination and filters for orientation, color, and content safety, an operation to retrieve a single photo by its id, and an operation that returns one or more random photos scoped to collections or topics. Requests carry your access key in the Authorization header, and responses deliver ready-to-use image URLs suited to headers, galleries, and backgrounds.
Install Jentic One Beta
Connect the Unsplash Photo API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Unsplash Photo API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2FUnsplash%2Funsplash" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2FUnsplash%2Funsplash" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Unsplash Photo API.
Search the Unsplash photo library by keyword with pagination
Filter search results by orientation, color, and content safety
Retrieve a single photo and its metadata by id
Fetch one or more random photos, optionally scoped to collections or topics
Use Cases
Patterns agents use Unsplash Photo API for, with concrete tasks.
★ AI Agent Image Selection
An AI content agent connected through Jentic searches Unsplash for a photo matching a topic, filters by orientation and content safety, and returns the image URL to drop into a draft. Because the search operation accepts a keyword and paging, the agent can offer a few candidates and let the user pick.
Search Unsplash for landscape photos of a topic, filter to safe content, and return the top three image URLs
CMS Header Image Search
A content management system lets editors search Unsplash inline when composing an article, filtering by orientation and color to match the page design. The system stores the returned image URL and attribution so each post ships with a properly credited header.
Search for wide-orientation photos matching an article title and return each result's image URL and photographer credit
Random Photo Backgrounds
An app refreshes a background or placeholder image by requesting a random photo scoped to a topic or collection, so each load shows a different high-quality picture. Filtering by orientation keeps the image sized correctly for the surface it fills.
Fetch a random portrait-orientation photo from a chosen topic and use its URL as the screen background
Key Endpoints
3 endpoints — the unsplash photo api searches and retrieves photos from the unsplash library and returns each with its urls and metadata.
METHOD
PATH
DESCRIPTION
GET
/search/photos
Search the Unsplash library by keyword with filters and pagination
GET
/photos/{id}
Retrieve a single photo and its metadata by id
GET
/photos/random
Fetch one or more random photos, optionally scoped to collections or topics
GET
/search/photos
Search the Unsplash library by keyword with filters and pagination
GET
/photos/{id}
Retrieve a single photo and its metadata by id
GET
/photos/random
Fetch one or more random photos, optionally scoped to collections or topics
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the Unsplash API by hand means registering an application, formatting the access key into the Authorization header, and shaping the query and filter parameters yourself. Through Jentic you install once, import Unsplash from the API Directory, store the key once, and your agent calls the search, detail, and random operations with structured inputs.
Permission scoping
The Unsplash endpoints are read-only photo lookups, so a rule can bound your agent to just the search and retrieval operations. You choose which operations it may call, so it can find and read photos and reach nothing else in your account.
Credential isolation
Your Unsplash access key is stored once, encrypted, by your own Jentic One instance and added to the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'search photos by keyword' or 'get a random photo', and Jentic returns the matching Unsplash operation with its input schema so the agent calls the right endpoint without reading the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Unsplash Photo API through Jentic.
What authentication does the Unsplash Photo API use?
The Unsplash Photo API authenticates with an API key: you pass your access key in the Authorization header on each request, per its OpenAPI spec. Through Jentic the key is stored once, encrypted, by your own Jentic One instance and added at call time, so it never enters the agent's prompt or logs.
Can I search photos by keyword and filter the results?
Yes. The search operation accepts a keyword query with pagination, plus filters for orientation, color, and content safety, and returns matching photos with their URLs. Retrieve a single photo by its id, or fetch random photos scoped to a collection or topic.
Is there an Unsplash MCP server?
You don't need an MCP server to give your agent the Unsplash API. Jentic connects it directly from the API Directory: import Unsplash, store your access key once, and your agent calls the photo search, detail, and random operations. Discovery happens on demand, so no extra server's tool definitions sit in the agent's context.
Can I limit what my agent is allowed to do with the Unsplash API?
Yes. Write a rule that permits only the photo search and retrieval operations, so the agent can find and read photos but reach nothing else in your Unsplash account, and every call it makes is logged. You choose the operations it may call, so nothing beyond read access is included unless you add it.
What are the rate limits for the Unsplash Photo API?
The OpenAPI spec does not specify rate limits. Check the Unsplash documentation at https://unsplash.com/developers for current limits and quota details.
How do I search Unsplash photos through Jentic?
Import the Unsplash API from the Jentic directory, store your access key once, and have your agent search with an intent such as 'find photos by keyword'. Jentic returns the search operation with its input schema so the agent supplies the query and filters and reads the image URLs. To run it on your own infrastructure, install Jentic One from its GitHub repo.
GET STARTED