Skip to content

Media Library ​

The media library provides a centralized place to manage all visual and file assets for your project. It supports direct uploads, URL imports, automatic image optimization, variant generation, and metadata management.

Managed service / Enterprise Edition

The media library is an Enterprise Edition feature, gated by the media.library and media.upload plan features and backed by Cloudflare R2 storage. It is available on Contentrain's managed service (Starter plans and above) and on self-hosted Enterprise Edition deployments. It is not available in the self-hosted Community Edition, which has no media storage backend.

Accessing the Library ​

Open the media library from:

  • Sidebar: Click Assets in the project sidebar
  • Command palette: Press Cmd+K and type "Media library"

The Assets panel: a drag-and-drop upload zone above a grid of media assets

Uploading Assets ​

Direct Upload ​

  1. Open the media library
  2. Drag and drop files onto the upload zone, or click Browse files
  3. The file is uploaded, optimized, and variants are generated
  4. Select the asset afterward to add alt text and tags

URL Import ​

You can import many files from external URLs in one run:

  1. Click Import from URLs
  2. Paste the URLs, one per line (a single run takes a limited number)
  3. Click Import
  4. Studio fetches, optimizes, and stores each file. URLs already in your library are skipped, and failed URLs stay in the box so you can retry them

Upload via AI Chat ​

The agent can upload images from URLs:

"Upload the image at https://example.com/hero.jpg as the hero banner
with alt text 'Product dashboard screenshot'"

Bulk Upload ​

Select or drop multiple files to upload them all at once. Each file is processed in turn with optimization and variant generation.

TIP

Supported formats are JPEG, PNG, GIF, WebP, AVIF, SVG, MP4, WebM, and PDF. Other file types are rejected.

CDN required

Assets are delivered over the CDN. Until the CDN is activated for the project, the library shows CDN not activated with a link to the CDN settings, and uploads stay private. See CDN.

Image Optimization ​

When you upload an image, Studio automatically:

  1. Converts to WebP — optimal format for web delivery (very large images are downscaled; animated GIF and WebP files have frame, pixel, and duration limits)
  2. Generates variants — multiple sizes for responsive design
  3. Computes blurhash — low-resolution placeholder for lazy loading
  4. Extracts metadata — dimensions, format, file size

Variants ​

Each uploaded image gets a set of size variants based on a preset. The default preset, hero-image, generates hero (1920x1080), card, thumb, and og (1200x630, JPEG). Other presets are avatar, gallery, icon, and logo. The agent's upload tool accepts a preset name. The uploaded original is kept and can be downloaded from the detail panel with Download original. Variants include:

PropertyDescription
pathStorage path for this variant
widthWidth in pixels
heightHeight in pixels
formatImage format (typically webp)
sizeFile size in bytes

Variant presets can be customized per field when defining image fields in your content models (Pro+ plan).

Asset Metadata ​

Every asset in the library has the following metadata:

An asset's detail panel: preview, dimensions, file size, storage path, generated variants (og, card, hero, thumb), alt text, and tags

FieldDescription
filenameOriginal file name
contentTypeMIME type (e.g., image/webp)
sizeFile size in bytes
widthImage width in pixels
heightImage height in pixels
formatFile format
blurhashLow-resolution placeholder hash
altAlt text for accessibility
tagsArray of organizational tags
sourceHow the asset was uploaded
variantsGenerated size variants

Editing Metadata ​

To update an asset's metadata:

  1. Click on an asset in the library to select it
  2. The detail panel shows the asset preview and metadata
  3. Edit the alt text or tags (comma-separated)
  4. Click Save

The agent's update_media tool can also set a focal point (x and y between 0 and 1); the detail panel has no focal point control.

WARNING

Always add descriptive alt text to images. It improves accessibility and helps the AI agent understand your media assets.

Browsing and Filtering ​

The media library provides several ways to find assets:

The expanded media library: search and sort controls above a grid of assets showing format and size

Type in the search bar (Search assets...) to filter the library.

Filter by Type ​

Filter assets by type:

  • All types — Show all assets
  • Images — JPEG, PNG, GIF, WebP, AVIF, SVG
  • Videos — MP4, WebM
  • Files — PDF

Sort Order ​

Sort assets by:

SortDescription
NewestMost recently uploaded first (default)
OldestOldest uploads first
NameAlphabetical by filename
SizeLargest files first

Pagination ​

The library loads 50 assets per page. Use pagination controls to browse through larger libraries.

Asset Preview ​

Click any asset to open a detailed preview:

  • Full-size preview — View the asset at its original dimensions
  • Metadata panel — Dimensions, storage used, upload date, delivery path (with a copy button), original file download, and variants
  • Edit controls — Update alt text and tags, or delete the asset

Using Assets in Content ​

image, video, and file fields store a string reference — there is no separate visual asset picker in v1. In the content editor (see the editor modal), enter a media path or external URL for the field:

  • A media library path, e.g. media/original/abc123.webp
  • An external URL, e.g. a CDN or Unsplash link

Via AI Chat ​

You can also reference media assets through the chat:

"Set the blog post cover image to the hero banner from the media library"
"Search for images tagged 'team' and use the first one as the about page photo"

The agent uses search_media and get_media tools to find assets and save_content to set image field values. get_media also returns where an asset is used, so check it before deleting.

Deleting Assets ​

To delete an asset:

  1. Select the asset in the library
  2. Click Delete in the detail panel

To delete multiple assets:

  1. Select multiple assets using checkboxes
  2. Click Delete in the bar that shows the selected count (or Clear selection to cancel)

WARNING

Deleting an asset does not automatically remove references to it in your content. Content fields that reference a deleted asset will show a broken reference.

Plan Limits ​

Media library features vary by plan:

FeatureFreeStarterProEnterprise
Browse library—YesYesYes
Upload—YesYesYes
Storage—5 GB25 GB100 GB
Max file size—10 MB50 MB100 MB
Variants per field—410Unlimited
Custom variantsNoNoYesYes

Next Steps ​

  • Content Editing — Use media assets in your content
  • AI Chat — Upload and manage assets through conversation
  • CDN — Deliver optimized assets through the CDN

Released under the AGPL-3.0 License. Privacy