Working with media in Contentful

How to create and use media files in your Contentful projects

For most of our users, media files (assets) are an integral part of their Contentful projects. That's why we've made creating, managing and delivering assets simple and flexible. With Contentful, assets can be uploaded manually within our web app or programmatically using our API. That includes images, videos, audio files, .pdfs, and more.

We make working with images easy by giving you a specialized API to manipulate images by simply changing URL parameters. The web app also has a built-in image editor for making more permanent changes. If you use an outside media editor or hosting service, try using one of our integrations or extensions to pull your files into our entry editor.

Keep reading to learn more about the cool things you can do with media in Contentful.

Creating new assets

There are two ways you can upload and create new assets: from inside the Contentful Web App or via our Content Management API.

Within the web app

To create a new asset, navigate to the Media tab in the top navigation bar and click the blue Add asset button. You can upload one asset or many assets at a time. Let's first upload a single asset.


Select either 'Single asset' or 'Multiple assets' from the menu.


Creating a new asset within the web app.

You can either drag your media file into the editor or select it using Filepicker. If you open the Filepicker window, you'll see a whole slew of possible file sources you can choose from, including Google Images, Facebook and, of course, your computer.


Media file source options in Filepicker.

Adding multiple assets at once

You can create new assets in bulk by selecting Multiple assets from the Add asset menu. Just like before, select the file source and choose which media files to upload. Filepicker also lets you select more than one source. For example, you can import images from your computer and Google Photos in the same bulk action. When you've selected all of the desired files, hit the Upload button.


Select multiple files to upload.

Naming and describing assets

After your asset(s) are done processing, it's time to give them some meta data. First, give your new asset a title. This doesn't necessarily need to be the title that will be displayed along with the file in your website or app. Rather, it is the title that will be used within the Contentful Web App to represent the file. We suggest giving it a descriptive title that adheres to your company's naming conventions.

You can also give your file a description, if you'd like. Again, it won't necessarily be displayed in your end project.


It's best to use easy to understand asset titles and descriptions.

Using the Content Management API

You can easily create assets via our CMA in just a few steps. It's also east to (un)publish, (un)archive and delete assets using the CMA. To learn how, check out our developer docs.

Managing assets

All of the assets you upload to Contentful live within the Media section of the web app. You'll notice that the Media section looks very similar to the general Content section, and has many of the same capabilities. Over on the left are your views, which can be reordered and customized to your liking. These views can be used to filter that big list of assets, and you can even create your own by clicking the black plus sign. Folders help you organize your saved views; group similar views under one folder to keep that sidebar looking clean.

Use the advanced search parameters to find all assets with 'cat' in their description.

Can't find that funny cat photo you need for your blog? Hit the down arrow on your keyboard for a list of advanced search parameters to fine-tune your search results. Need to be able to quickly get back to that cat photo later? Create a new saved view using your search results.

Creating a saved view for 'Funny Cats'.

Bulk actions

Perform bulk actions on assets using the checkboxes to the left of each item in the Media Library. Depending on the status of the asset you have the option to (un)publish, delete, duplicate, and (un)archive.


Performing bulk actions on assets in the Media Library.

Editing image assets

You can edit your uploaded from right within our web app! First open your asset in the Media section, then click the box that says Edit file. Within the image editor you can do basic edits like cropping, resizing, and rotating your image, as well as fun things like adding overlays or making it into a meme.


You can use the built-in image editor to make your photos black & white.

Images API

Our Images API lets you perform dynamic actions on your images by simply changing the URL. For example, instead of uploading multiple versions of an image to fit various screen sizes, you can use one asset and resize it on the fly. Some of the transformations you can do are resizing, cropping (including creating thumbnails), and changing the image's resolution. There's more about the Images API in our developer docs.

For example, here's two ways to transform the same image, just by changing the URL:



Working with meta data

By default, created assets have fields for a title and a description. If you need more meta data fields, there's a simple workaround! You can create a content type to be used for your media files and include fields for any meta data necessary. This also means you can have different fields available for each kind of media file you use, so your custom 'Image' content type can have more or less meta data fields than your created 'Video' content type.


Example content type for images with meta data


The above 'Image' content type as seen in the entry editor

Keep in mind that when you want to use a new media content type, you'll want to link them to an entry using a Reference field. The media file will now be held within its own entry, rather than from the Media library directly. This also means you will find the media file + meta data entry within the Content section of the web app, not in the Media library. The original asset will remain within the Media Library.


Note the field referencing an entry 'Hamburg 01' of content type 'Image'.


On our Ecosystem page you can check out what integrations we offer with other platforms. Here are a few examples:

Getty Images - Browse the Getty Images library of over 80 million stock images and insert them directly into Contentful.*

YouTube - Paste the URL to your YouTube videos and preview them in the entry editor.

Kaltura - Pull in videos from the popular open-source video platform.*

Ooyala - Link directly to videos from your Ooyala library.*

* Enterprise plans only. To learn more, get in touch!

Don't see an integration with the media platform you use? Create a custom UI extension and pull in media from virtually anywhere.

Discover more Contentful.

If you enjoyed this article, you might like our product as well.

What our product does

Take a look at the API capabilities, delivery infrastructure and friendly editing environment.
See features

What our clients built

From apps and sites to digital signage and iBeacon campaigns — we deliver content everywhere.
See real-life examples