Upload media without surprises#

An upload creates a reusable media item for the current website. The simplest successful upload is: choose the correct website, add a supported file, describe it, and then select it from a content field.

Check the file first#

Before uploading, make sure the file is one of the server-supported formats and no larger than 10 MB.

Supported file	MIME type	Good for
`.jpg` or `.jpeg`	`image/jpeg`	Photos and screenshots
`.png`	`image/png`	Transparent graphics
`.webp`	`image/webp`	Optimized web images
`.gif`	`image/gif`	GIF graphics
`.pdf`	`application/pdf`	Documents visitors download

The final check happens on the server. A filename and browser-reported MIME type must match the file content, so renaming an unsupported file does not make it uploadable.

Warning

Do not plan an upload workflow around SVG, MP4, MP3, DOCX, or arbitrary file types yet. They are not accepted by the current upload API.

Upload one file#

Open Media Library and confirm the selected website.
Open the folder where the item should live, or stay at the library root.
Choose Upload media and select a file.
Add alt text for an informative image. This can also be edited after upload.
Save the upload, then open the item details to add any remaining metadata.
Select the item from a Media, Image, Gallery, or compatible component field.

Here is a clear example for a product image:

Example media details

File: cloud-desk-blue.jpg
Name: Cloud Desk dashboard
Alt text: Blue Cloud Desk dashboard displayed on a laptop
Caption: Plan work and monitor team activity from one dashboard.
Folder: Products / Cloud Desk
Tags: cloud-desk, dashboard

The stored media record has its own ID and URL. A content entry normally stores a reference to that record, which lets editors reuse the same asset instead of copying it.

Upload several files#

Use Bulk upload when the files belong together, such as a product gallery or campaign imagery. You can choose a folder for the batch and then add detailed metadata to the individual items afterward.

For a batch of 20 images, use a small naming convention before uploading:

Helpful filenames

spring-campaign-hero.jpg
spring-campaign-card-01.jpg
spring-campaign-card-02.jpg
spring-campaign-social.jpg

This makes search, review, and later replacement much easier than relying on a camera's default names.

Add metadata after upload#

The media editor supports the following fields. Add only what is useful for the item and your publishing process.

Field	When to use it	Example
Alt text	An image conveys information to a visitor.	`A support agent reviewing a customer request`
Title	A short internal or display label.	`Support team photo`
Caption	The page should show explanatory text near the item.	`Our support team is available around the clock.`
Description	Editors need more context than a title provides.	`Approved photo for careers and support pages`
Credit / copyright	The asset has attribution or licensing requirements.	`Photo: A. Patel, 2026`
Focal point	Editors want to record an important area of an image.	The person's face in a wide photo

Focal point is currently stored as media metadata. Do not assume it changes a delivered crop automatically: the standard delivery media response does not expose it, and generated variants use their own processing rules.

Use the uploaded item in the frontend#

For most pages, select the item in the CMS field and render the media data from the delivered page or entry. If an application only has the media ID, use the core SDK on the server:

app/products/[slug]/media.ts

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

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

export async function getProductImage(mediaId: string) {
  return client.media.get(mediaId);
}

The standalone media route requires media:read on the API client. Keep the key in server-side environment variables; do not put it in NEXT_PUBLIC_ variables or browser code.

Troubleshooting#

Problem	Check this first
`File too large`	Reduce the source file to 10 MB or less.
`Unsupported file type`	Use one of the supported JPG, PNG, WebP, GIF, or PDF formats.
File extension and content type do not match	Export the file again from a trusted application instead of renaming it.
Image has no thumbnail yet	Processing happens in the background. Refresh after a short wait, then check the image's variants.
The item cannot be found in a field picker	Confirm the current website and the field's allowed media type.
The wrong image appears on a page	Check the media reference on the entry or component, then preview before publishing.

Before you publish#

Confirm that you are allowed to use the file.
Check the image crop at the real component size, especially on mobile.
Verify alt text, caption, and attribution.
Search for an existing item before adding a duplicate.
Review usage before replacing a shared file.

For sizing and crop choices, continue to Image Processing. For reusable editor groups, see Collections.

Uploading Media