Image Search Sources
x_image_search draws on five image libraries: Openverse, Wikimedia Commons, Pexels, Pixabay and Unsplash. Every result carries its own license record, read per image: what the license allows, the credit it needs, and whether you may host a copy. This page lists the sources Erebine can search and what each one's results carry.
- sources
- 5
- license filter
commercial,no_attribution,any_open- tools
x_image_search,x_fetch_image- mcp
erebine.research.image_search
Overview
One search reaches every source at once and returns their results together. Two sources mix licenses within their collection, so the license is read for each image, never assumed for the source. A result whose license is not one Erebine recognizes is dropped rather than offered under guessed terms.
| Source | Licenses | Credit required | Hosted copy | Safe search |
|---|---|---|---|---|
Openverse openverse |
Creative Commons and public domain, per image | Yes, except CC0 and the Public Domain Mark | Yes | Leaves out works Openverse marks as mature |
Wikimedia Commons wikimedia |
Free licenses and public domain, per file | Per file | Yes | Category filter, best effort |
Pexels pexels |
Pexels License | No | Yes | Curated library |
Pixabay pixabay |
Pixabay Content License | No | Yes, and the only permitted use | Images Pixabay marks suitable for all ages |
Unsplash unsplash |
Unsplash License | Yes | No: embed from Unsplash | Unsplash's strictest content filter |
The code after each name is its provider value in a result and
its value in the providers parameter. Hosted copy is the
result's can_host_copy: whether
x_fetch_image downloads the
file for you to store and serve. Which of these sources a search reaches
depends on the deployment; see Available Sources.
Openverse
Openverse is a search engine for openly licensed media, run as a WordPress project. Its index gathers images from Flickr, Wikimedia Commons, museum collections and other open sources, so its results link back to the site that holds each work.
| Property | Value |
|---|---|
| Licenses | Per image: CC BY, CC BY-SA, CC BY-ND, CC BY-NC, CC BY-NC-SA, CC BY-NC-ND, CC0 and the Public Domain Mark, at the version the work carries. license_code reads like cc-by-sa-4.0, cc0-1.0, pdm-1.0. Works under any other license are dropped. |
| Credit | attribution_text names title, author and license, for example "Harbor at dusk" by jdoe, CC BY 2.0. attribution_url and source_page are the work's page at its original source. |
| Hosted copy | Yes. Every Creative Commons license and public-domain tool permits copying. |
| Files | full_url is the file at the site that holds the work; preview_url is an Openverse thumbnail. |
| Safe search | On: works Openverse marks as mature are left out. Off: they are included. |
| Links | openverse.org; license texts at creativecommons.org/licenses |
Wikimedia Commons
Wikimedia Commons is the Wikimedia Foundation's repository of freely
licensed media, searched directly. Commons accepts only free content,
which its licensing policy requires to permit commercial use and
modification, so every Commons result passes the
commercial filter.
| Property | Value |
|---|---|
| Licenses | Per file, as Commons records it: Creative Commons licenses, including national ports such as cc-by-3.0-de, CC0, public domain, and other free licenses such as the GFDL. license_name is Commons' own short name. |
| Credit | attribution_text names title, author and license, for example "Smoked brisket" by Jane Doe, CC BY-SA 4.0, linked to the file's description page. attribution_required is the file's own flag; public-domain files usually need none. |
| Hosted copy | Yes. |
| Files | JPEG, PNG, GIF and WebP only. full_url is the original upload, which can exceed the limits x_fetch_image accepts; it then returns the preview in its place and attachment_note says why. |
| Left out | Files Commons marks with restrictions such as trademarks or personality rights, and files it marks non-free. |
| Safe search | Commons has no adult-content filter of its own. On: files filed in a category whose name marks adult content are dropped. The check reads a file's own categories, not their parents, so it is best effort. |
| Links | commons.wikimedia.org; Commons licensing policy; reusing Commons content |
Pexels
Pexels is a curated library of stock photos shared by its photographers. Every photo is under one license.
| Property | Value |
|---|---|
| License | The Pexels License: free to use, commercial use and modification included, no attribution required. |
| Credit | attribution_text is Photo by Jane Doe on Pexels. attribution_url is the photo page; attribution_site is Pexels, with attribution_site_url the Pexels home page. Credit is optional under the license; Pexels asks for a link back to Pexels and for photographer credit where possible. |
| Hosted copy | Yes. |
| Files | full_url is the original file; preview_url is a 350 px tall rendition. |
| Safe search | Pexels curates its library; no further filter is applied. |
| Links | pexels.com; Pexels License |
Pixabay
Pixabay is a library of free images shared by its community. Searches return photos only, not Pixabay's illustrations or vectors.
| Property | Value |
|---|---|
| License | The Pixabay Content License: free to use, commercial use and modification included, no attribution required. It bars selling unaltered copies on their own and using an image as part of a trademark. |
| Credit | attribution_text is Image by jdoe from Pixabay. attribution_url is the image page; attribution_site is Pixabay, with attribution_site_url the Pixabay home page. Optional under the license; Pixabay asks that search results show where their images come from. |
| Hosted copy | Yes, and required: hotlink_allowed is false. Pixabay's URLs expire and may not be embedded permanently, so fetch the file with x_fetch_image and serve your own copy. |
| Files | full_url is the large rendition, at most 1280 px on its long side. A repeated search can return results up to 24 hours old, as Pixabay's API terms require. |
| Safe search | On: only images Pixabay marks suitable for all ages. |
| Links | pixabay.com; Pixabay Content License |
Unsplash
Unsplash is a library of photos contributed by its community of photographers. Its API guidelines set two rules the results carry: credit the photographer and Unsplash, and show the photo from Unsplash's own servers.
| Property | Value |
|---|---|
| License | The Unsplash License: commercial use allowed. Through the API, credit is required. |
| Credit | attribution_text is Photo by Sam Lee on Unsplash. Link the photographer's name to attribution_url, their Unsplash profile, and the word Unsplash to attribution_site_url, the Unsplash home page. These links and source_page, the photo page, carry Unsplash's utm_source and utm_medium=referral parameters. Keep them on every link. |
| Hosted copy | No: can_host_copy is false. Embed full_url or preview_url exactly as returned, query string included. For each photo you use, call x_fetch_image once: it downloads nothing, registers the use with Unsplash, and answers use_reported: true with the URL to embed. When an Erebine answer places an Unsplash photo, the use is registered even without that call. |
| Files | full_url is the full-size photo; preview_url is a 400 px wide rendition. |
| License filter | Not searched under no_attribution; listed under providers.skipped with the reason. |
| Safe search | On: Unsplash's high content filter, which also removes content unsuitable for younger audiences. Off: Unsplash's default filter, which still excludes content that breaks its submission guidelines, such as nudity or violence. |
| Links | unsplash.com; Unsplash License; Unsplash API guidelines |
In chat, Unsplash photos load straight from Unsplash's image servers, with no referrer, both as search thumbnails and inline in answers, as Unsplash requires. Images from every other source load through your Erebine origin. When an answer places an Unsplash photo, Erebine registers the use with Unsplash.
License Filter
The license parameter filters on what you intend to do with
an image, not on any one source's vocabulary. Every result is checked
against it. A source whose single license the filter rejects is not
searched and is listed under providers.skipped with the
reason.
| Value | Admits | Sources it reaches |
|---|---|---|
commercial |
Licenses that permit commercial use. Credit may still be required. | Openverse (no NC licenses), Wikimedia Commons, Pexels, Pixabay, Unsplash |
no_attribution |
Licenses that permit commercial use and require no credit. | Openverse (CC0 and the Public Domain Mark), Wikimedia Commons (files that need no credit), Pexels, Pixabay |
any_open (default) |
Every recognized open license, non-commercial ones included. | All five |
Use commercial or no_attribution for a business
site. Under any_open, check commercial_use before
you use a result commercially.
License Fields
Every result, and every x_fetch_image response, carries the
same flat license fields beside its own. The full result shape is in
x_image_search.
| Field | Type | Meaning |
|---|---|---|
license_code |
string | Stable machine code: cc-by-sa-4.0, cc0-1.0, pdm-1.0, pexels, pixabay, unsplash, or a Commons code such as pd. |
license_name |
string | Display name, for example CC BY-SA 4.0. |
license_url |
string | The license text. |
commercial_use |
boolean | Whether the license permits commercial use. |
attribution_required |
boolean | Whether the license requires crediting the author. |
can_host_copy |
boolean | Whether you may store and serve a copy of the file. |
hosting_restriction |
string | Why a copy is not permitted. Present only when can_host_copy is false. |
hotlink_allowed |
boolean | Whether the source's file URLs may be embedded in a page. |
attribution_text |
string | Ready-to-display credit line. |
attribution_url |
string | The page the name in the credit line links to: the photographer's profile for Unsplash, the image's page for every other source. |
attribution_site |
string | The site the credit line names: Pexels, Pixabay or Unsplash. Absent for Openverse and Wikimedia Commons, whose credit names the work's own source. |
attribution_site_url |
string | The page the site name in the credit line links to. Present exactly when attribution_site is. |
photographer |
string | The photographer or author, when the source names one. |
source_page |
string | The image's page on the source's site. |
Using a Result
Two fields decide how an image may reach your page.
can_host_copy |
hotlink_allowed |
Do this | Sources |
|---|---|---|---|
true |
true |
Embed full_url, or fetch the file with x_fetch_image and serve your copy. |
Openverse, Wikimedia Commons, Pexels |
true |
false |
Fetch the file with x_fetch_image and serve your copy. Do not embed its URLs; they expire. |
Pixabay |
false |
true |
Embed full_url as returned, and call x_fetch_image once to register the use. Never copy the file. |
Unsplash |
Crediting an Image
Show attribution_text with the image, linked to
attribution_url. When attribution_required is
true the credit is a license condition. When it is
false the license does not demand it, but Pexels and Pixabay
ask applications to show where their images come from, and the credit
line does that.
Creative Commons and Commons Files
The credit line follows the Creative Commons recommendation: title,
author and license, with the source as its link. Link the license name to
license_url as well; the CC licenses ask for a link to their
text. A license code tells you what else applies:
| Code contains | Means |
|---|---|
by |
Credit the author. |
sa |
Share an adapted image under the same license. |
nd |
Share the image only unadapted. |
nc |
No commercial use; commercial_use is false. |
cc0, pdm, pd |
Public domain: no conditions. |
<figure>
<img src="https://live.staticflickr.com/65535/53000000000_0a1b2c3d4e_b.jpg"
alt="Harbor at dusk">
<figcaption>
<a href="https://www.flickr.com/photos/jdoe/53000000000">"Harbor at dusk" by jdoe</a>,
<a href="https://creativecommons.org/licenses/by/2.0/">CC BY 2.0</a>
</figcaption>
</figure>
Stock Libraries
A Pexels, Pixabay or Unsplash credit carries two links. Inside
attribution_text, link photographer to
attribution_url and attribution_site to
attribution_site_url. Unsplash credit is required, and its
links keep their referral parameters as returned.
<figure>
<img src="https://images.unsplash.com/photo-1600000000000-0a1b2c3d4e5f"
alt="Brisket on a cutting board">
<figcaption>
Photo by <a href="https://unsplash.com/@samlee?utm_source=erebine&utm_medium=referral">Sam Lee</a>
on <a href="https://unsplash.com/?utm_source=erebine&utm_medium=referral">Unsplash</a>
</figcaption>
</figure>
On the Responses API each result's pages become citation sources titled
with the credit line, so a link to one of them in the answer carries a
url_citation annotation; see
Web Search.
Results From Several Sources
- Interleaved. Results are taken one from each source in turn up to
count, so no single source fills the page. - De-duplicated. A file URL already taken is skipped. Openverse indexes Wikimedia Commons, so the same file can arrive from both; only its first copy is kept.
- Re-checked. Every result is checked again against the license filter,
orientationandmin_width, whatever the source's own filters returned. - Reported.
providers.answerednames the sources that answered,providers.failedthose that failed or timed out, andproviders.skippedthose not searched, each with a reason. - Partial, not empty. When a source fails, the others' results still return and
noticeleads withSearch backends degraded:: a missing image is then not evidence that none exists.
Available Sources
These are the sources Erebine can search. Which of them a search reaches
depends on the deployment, and every response says so. Without
providers, a search reaches every available source the license
filter admits, and providers.answered names the ones that
answered. Name a source in
providers that is not available and it is listed under
providers.skipped with the reason
it is not configured on this deployment.
{
"name": "x_image_search",
"arguments": {
"query": "harbor at dusk",
"license": "no_attribution",
"providers": ["openverse", "wikimedia"]
}
}
Each source sets its own rate limits. A source at its limit is listed
under providers.failed with the reason
the provider rate limit was reached; retry later, or
search the other sources meanwhile.