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+Kand type "Media library"

Uploading Assets
Direct Upload
- Open the media library
- Drag and drop files onto the upload zone, or click Browse files
- The file is uploaded, optimized, and variants are generated
- Select the asset afterward to add alt text and tags
URL Import
You can import many files from external URLs in one run:
- Click Import from URLs
- Paste the URLs, one per line (a single run takes a limited number)
- Click Import
- 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:
- Converts to WebP — optimal format for web delivery (very large images are downscaled; animated GIF and WebP files have frame, pixel, and duration limits)
- Generates variants — multiple sizes for responsive design
- Computes blurhash — low-resolution placeholder for lazy loading
- 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:
| Property | Description |
|---|---|
path | Storage path for this variant |
width | Width in pixels |
height | Height in pixels |
format | Image format (typically webp) |
size | File 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:

| Field | Description |
|---|---|
filename | Original file name |
contentType | MIME type (e.g., image/webp) |
size | File size in bytes |
width | Image width in pixels |
height | Image height in pixels |
format | File format |
blurhash | Low-resolution placeholder hash |
alt | Alt text for accessibility |
tags | Array of organizational tags |
source | How the asset was uploaded |
variants | Generated size variants |
Editing Metadata
To update an asset's metadata:
- Click on an asset in the library to select it
- The detail panel shows the asset preview and metadata
- Edit the alt text or tags (comma-separated)
- 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:

Search
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:
| Sort | Description |
|---|---|
| Newest | Most recently uploaded first (default) |
| Oldest | Oldest uploads first |
| Name | Alphabetical by filename |
| Size | Largest 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:
- Select the asset in the library
- Click Delete in the detail panel
To delete multiple assets:
- Select multiple assets using checkboxes
- 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:
| Feature | Free | Starter | Pro | Enterprise |
|---|---|---|---|---|
| Browse library | — | Yes | Yes | Yes |
| Upload | — | Yes | Yes | Yes |
| Storage | — | 5 GB | 25 GB | 100 GB |
| Max file size | — | 10 MB | 50 MB | 100 MB |
| Variants per field | — | 4 | 10 | Unlimited |
| Custom variants | No | No | Yes | Yes |
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