Media

The Media Library in the admin handles upload, folders, alt text, moving and deletion. Uploading, moving, editing and deleting media needs the Editor role or above.

Uploads

Accepted types: PNG, GIF, JPEG and WebP.
The type is determined from the file’s actual bytes. The filename extension and the browser’s Content-Type are not trusted.
Maximum size: 10 MB per file.
Width and height are recorded for PNG, GIF, JPEG and WebP. Alt text is editable after upload.

Using media in entries

A media field shows a thumbnail of the chosen file with its name. Click the thumbnail to open a larger preview. url fields only offer the Media Library when the field allows it (see Content model).

Folders

Media can be organized in named folders. A folder has a slug, and a frontend can fetch every item in one folder with cms.media.byFolder({ slug }). That lets you curate a set (for example a hero image set) instead of guessing ids from the flat library.

The Media Library shows one folder at a time by default; a View all media toggle switches to every item across every folder. Either view is paginated rather than rendering the whole library at once.

Importing from Pixabay

The media picker’s From Pixabay tab searches Pixabay’s photo library by keyword, previews the result, and imports it into your Media Library (downloaded and stored in R2, never hot-linked), with alt text and a destination folder.

It needs a free Pixabay API key, which you provide in one of two ways:

From the CMS (Admins and Owners): Settings → API → Image sources → paste the key. It’s stored encrypted in the database, is never shown again, and can be replaced or removed at any time.
As a Worker secret: wrangler secret put PIXABAY_API_KEY. If both are set the Worker secret wins, and the Settings card says so.

Without a key the tab explains how to add one. Picsum keeps working with no key.

Only pixabay.com image URLs are ever downloaded, and Pixabay’s results are cached for an hour at the edge, well inside its rate limit.

Importing from Picsum

The media picker’s From Picsum tab imports a stock photo from picsum.photos without leaving the entry editor — no API key needed. It’s downloaded server-side and stored in R2 like any other upload, never hot-linked, so the file survives Picsum changing or removing the source image.

Two ways to pick a photo:

Browse the catalog grid, click one to preview it full-size, then import. The import defaults to the photo’s own native resolution rather than a fixed downscale, preserving quality; you can adjust width/height before importing.
Search by seed for a specific, repeatable photo (Picsum’s /seed/{seed} convention) when you already know what you want, without browsing the catalog.

Either way you can apply grayscale and a blur amount, and choose a destination folder before importing.

Using media

Add a media field to a content type, or insert an image into a rich text field. A media field stores the media item’s id and shows a real thumbnail preview, including immediately after a fresh upload or Picsum import. To render one on your site see Astro media; the underlying endpoints are in Public API.

Media has no draft state. Once uploaded, a file is reachable through its public URL by anyone who has its id. Deleting it removes the file and invalidates its cache entry.

See Media architecture for how files are stored and cached.