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 a UI Extension to pull your files into our entry editor.

Keep reading to learn more about the 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.



You can either drag your media file into the editor or select it from your local machine. You can also choose from multiple external sources, including Google Images, Instagram or Facebook.


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. 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.


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.


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.

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.

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.


Editing image assets

You can edit your uploaded files from right within our web app! First open your asset in the Media section, then click on any of the overlay buttons to resize, crop or rotate the image.


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.



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.


UI Extensions

Any third party media service can be used with Contentful as long as they offer an API we can query from a custom UI Extension. Create a custom UI Extension and pull in media from virtually anywhere.