---
url: /en/docs/integrations/stock-photos.md
description: >-
  Search and insert free stock photos from popular providers directly in Sveltia
  CMS.
---

# Stock Photos

Sveltia CMS includes built-in support for integrating free stock photo services directly into the media storage. This allows content creators to easily search for and insert high-quality images into their content without leaving the CMS interface.

## Supported Services

Currently, Sveltia CMS supports the following free stock photo providers:

* [Lorem Picsum](https://picsum.photos/)
* [Pexels](https://www.pexels.com/)
* [Pixabay](https://pixabay.com/)
* [Unsplash](https://unsplash.com/)

::: info Future Plans

More providers, including paid stock photo services, will be added in future releases.

:::

### Note on Lorem Picsum

* You don’t need an API key to use Lorem Picsum, so it’s the easiest option to get started with stock photos in Sveltia CMS.
* Their pictures are mainly for placeholder use, so they may not be suitable for all types of content. However, they can be a great option for testing or when you need generic images without specific themes.
* Their pictures are [CC0 licensed](https://github.com/DMarby/picsum-photos/issues/81#issuecomment-1340068800), which means they are free to use without giving credit to the creator.
* You can access 300 random pictures quickly, but you cannot search for specific images using keywords because the images do not have tags or captions due to the nature of the service.
* Unfortunately, there is no alternative text for the images because they do not have tags or captions. This makes them inaccessible to some users.

### Non-hotlinking Providers

Due to the non-hotlinking policies, Pexels and Pixabay are disabled if the [internal media storage](/en/docs/media/internal) is disabled due to the lack of the [`media_folder` option](/en/docs/media/internal#media-folder) in the configuration. They are also hidden for a field where the internal media storage is [disabled](/en/docs/media/internal#disabling-internal-media-storage-for-a-field) with `media_libraries.default: false`.

## Requirements

Except for Lorem Picsum, which does not require an API key, you must obtain API keys for each stock photo service you wish to use. Register for developer accounts at the following links to get your API keys:

* [Pexels API](https://www.pexels.com/api/)
* [Pixabay API](https://pixabay.com/service/about/api/)
* [Unsplash API](https://unsplash.com/developers)

### CSP

If your site uses a Content Security Policy (CSP), you may need to update it to allow requests to stock photo providers. See the [CSP documentation](/en/docs/security#setting-up-content-security-policy) for more details.

## Configuration

No additional configuration is required to enable stock photo providers, as they are included by default. However, developers can customize which providers are available or disable them entirely.

To enable or disable specific stock photo providers, you can modify the `providers` array in the `media_libraries` section of your `config.yml` file. For example, to enable only Unsplash, you would configure it as follows:

::: code-group

```yaml [YAML]
media_libraries:
  stock_assets:
    providers:
      - unsplash
```

```toml [TOML]
[media_libraries.stock_assets]
providers = ["unsplash"]
```

```json [JSON]
{
  "media_libraries": {
    "stock_assets": {
      "providers": ["unsplash"]
    }
  }
}
```

```js [JavaScript]
{
  media_libraries: {
    stock_assets: {
      providers: ["unsplash"],
    },
  },
}
```

:::

To disable stock photo providers, you can set the `providers` array to be empty in the `media_libraries` section of your `config.yml` file, as shown below:

::: code-group

```yaml [YAML]
media_libraries:
  stock_assets:
    providers: []
```

```toml [TOML]
[media_libraries.stock_assets]
providers = []
```

```json [JSON]
{
  "media_libraries": {
    "stock_assets": {
      "providers": []
    }
  }
}
```

```js [JavaScript]
{
  media_libraries: {
    stock_assets: {
      providers: [],
    },
  },
}
```

:::

Setting `stock_assets` to `false` also disables all the providers.

The `stock_assets` option can be set for an individual [Image](/en/docs/fields/image) field under its `media_libraries` option as well. The field-level options are merged over the top-level ones, so a field can offer a different set of providers, or none.

## Using Stock Photos

Stock photos can be accessed directly from the [Image](/en/docs/fields/image) field in the Sveltia CMS interface. When opening the Select Images dialog, stock photo options are shown alongside the existing media storage.

Select the desired stock photo provider and provide an API key to enable the service. API keys are stored securely in the browser’s local storage, so users don’t need to enter them every time. Lorem Picsum doesn’t require an API key, so it will be available immediately without any configuration.

By default, curated images from each provider are available for quick access. You can also use the search functionality to find specific images based on keywords. Lorem Picsum doesn’t support searching as mentioned earlier, so it will only show random images.

Once the desired image is found, simply select it, and it will be inserted into the content just like any other media asset. The CMS may show a dialog where you can copy the image credit information to comply with attribution requirements.

Note that some providers require hotlinking to the image’s original URL, while others rather disallow hotlinking. Sveltia CMS handles this automatically based on the provider’s policies, and downloads the image to the media storage if necessary.

::: tip Multi-user setups

If your CMS instance is used by multiple users, the administrator needs to distribute an API key to all users to let them use the stock photo feature.

Alternatively, each user can provide their own API key. However, this is not recommended for instances with non-technical end-users because generating and managing API keys may be challenging for them.

:::