canonical: https://jentic.com/apis/Unsplash/unsplash # Unsplash Photo API 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. ## For AI 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. ## Scope Does not upload, edit, or license photos, and does not process image files. Use for searching and retrieving Unsplash photos only. ## Capabilities - 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 ### 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. Example prompt: 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. Example prompt: 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. Example prompt: Fetch a random portrait-orientation photo from a chosen topic and use its URL as the screen background ## Key endpoints | 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 | ## Key resources - **Photos** — Search the library by keyword, retrieve a single photo by id, and fetch random photos with URLs and metadata ## Why Jentic - **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 handling:** 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. - **Discovery method:** 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 - **Pexels API** — Pexels offers free stock photos and videos through a search API. - **Getty Images API** — Getty Images provides licensed editorial and creative photography. - **Flickr API** — Flickr exposes a large community photo library with rich search. ## FAQ ### 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.