Media, in simple terms#

The Media Library is the place to keep files that editors want to reuse. Instead of pasting an image URL into every page, upload the file once and choose that media item in a content or component field.

That gives a team one source of truth for the file, its accessibility text, its folders, its tags, its versions, and any generated image sizes.

A typical media flow

Upload a file -> describe it -> organize it -> select it in content -> preview -> publish

For example, a marketing editor can upload cloud-desk-dashboard.jpg, add meaningful alt text, and select it in both a Hero and a Product Card. The page stores a reference to the media item. It does not need a second copy of the file.

What you can upload today#

The server currently accepts these file types, up to 10 MB each:

File type	Accepted MIME type	Typical use
JPG or JPEG	`image/jpeg`	Photography and screenshots
PNG	`image/png`	Images that need transparency
WebP	`image/webp`	Compressed web images
GIF	`image/gif`	Simple animated or legacy graphics
PDF	`application/pdf`	Downloadable documents

Contoprix checks the filename extension, declared MIME type, and file signature before storing a file. SVG, video, audio, and other document formats are not accepted by the current upload API, even if a file picker elsewhere appears to offer them.

Important

Choose the website before you upload or search. Media is scoped to one website, so an asset uploaded for one website is not automatically available to another.

The words you will see in the library#

Term	What it means	Simple example
Original	The file you uploaded.	`team-photo.jpg`
Metadata	Information that describes the file.	Alt text, caption, credit, and copyright
Folder	One place for an item in the library hierarchy.	`Editorial / Case studies`
Tag	A label that can be attached to many items.	`launch-2026`
Collection	A named, reusable list of media items.	`Spring campaign`
Variant	A derived image size or edited rendition.	`thumbnail` or `medium`
Version	A historical copy created when a file is replaced.	The previous logo file
Usage	A recorded place where an asset is referenced.	`hero.image` on an About page

Folders, tags, and collections solve different problems. Use a folder for where an editor expects to find an asset, tags for cross-cutting labels, and a collection for a deliberate group that can include files from several folders.

Your first media item#

Try this small workflow before organizing the whole library:

Open the Media Library for the correct website.
Upload one image, such as product-dashboard.jpg.
Add a useful name and alt text. For a meaningful image, describe its purpose, not just its colors.
Put it in a folder such as Products / Cloud Desk.
Select it from an image or media field in a content entry or Visual Builder component.
Preview the page at the size where visitors will see the image.
Publish the page or entry when the result is correct.

Example metadata for that image:

Suggested metadata

Name: Cloud Desk dashboard
Alt text: Cloud Desk analytics dashboard shown on a laptop
Caption: Review activity, tasks, and team progress in one place.
Credit: Contoprix product team
Folder: Products / Cloud Desk
Tags: cloud-desk, dashboard

If the image is purely decorative, use the conventions your design and accessibility team have chosen. Do not invent a noisy description just to fill a field.

Use media in a website#

When a page or content response already contains a resolved media field, use the URL and accessibility information that came from Contoprix. When you only have a media ID, the JavaScript SDK can fetch the delivery record:

lib/media.ts

import { ContoprixClient } from "@contoprix/client";

const contoprix = new ContoprixClient({
  baseUrl: process.env.CONTOPRIX_BASE_URL!,
  auth: {
    type: "deliveryKey",
    deliveryKey: process.env.CONTOPRIX_DELIVERY_KEY!,
  },
});

export async function getMedia(mediaId: string) {
  return contoprix.media.get(mediaId);
}

Render the returned values rather than constructing a storage URL yourself:

components/MediaImage.tsx

import type { ContoprixMedia } from "@contoprix/client";

export function MediaImage({ media }: { media: ContoprixMedia }) {
  return (
    <img
      src={media.url}
      width={media.width}
      height={media.height}
      alt={media.altText ?? ""}
    />
  );
}

Keep this request on the server. Fetching a standalone media record requires an API client with the media:read scope. A published page or content response can already include its resolved media fields when it is delivered with delivery:read.

Good habits that prevent problems#

Use descriptive names such as cloud-desk-dashboard-2026.jpg, not IMG_0042.jpg.
Search before uploading so the library does not fill with duplicates. The upload response can identify a file with the same content hash, but it does not silently block every duplicate.
Add alt text when the image conveys information. Keep captions, credits, and copyright details when they are needed by the team.
Use the image editor or variants for a new crop or size; CSS alone does not make the downloaded file smaller.
Check an item's recorded usage before replacing, archiving, or deleting it.
Never hard-code /uploads/... paths in application code. Storage and delivery URLs can change between environments.

Next, learn how to upload media, organize it with collections, and choose a variant for the final page.