Edit an image for the place where it appears#

An original photo is often too large or the wrong shape for the component where visitors see it. Contoprix can create a processed image without forcing editors to upload the same file again.

The image editor supports raster JPEG, PNG, and WebP media items. GIFs can be uploaded but are not supported by the processing endpoint.

Choose the right outcome first#

Before opening the image editor, decide whether you need a variant or a new asset.

Choice	Use it when	What happens
Save as a variant	The same original should serve another size or crop.	A new rendition is attached to the existing media item.
Save as a new asset	The result has a different editorial purpose.	A separate media item is created, with the original metadata and folder copied.

Example: create a hero variant for a wide banner, but save a heavily cropped customer portrait as a new asset if it will have its own approvals and usage.

Simple hero-image recipe#

Suppose you uploaded a 2400 x 1600 product photo and need a wide hero.

Open the image in the Media Library and choose Edit image.
Draw a crop around the important subject. For a wide hero, use a landscape ratio such as 16:9.
Resize the result to the display size you need, such as 1600 x 900.
Keep aspect ratio enabled unless you intentionally want to stretch the image.
Choose WebP or JPEG for a photographic hero. Use a quality value that still looks clear in the real page.
Choose Save as variant and give it a clear type, such as hero.
Preview it in the Hero component on desktop and mobile.

The processing API can crop, resize, rotate, flip, and encode the edited result:

Operation	Useful example
Crop	Remove empty space around a product
Resize	Make a 1600 px hero or 400 px card image
Rotate	Correct a sideways source image by 90, 180, or 270 degrees
Flip	Correct a mirrored image when appropriate
Format	Output JPEG, PNG, or WebP
Quality	Choose a value from 1 to 100

Card image versus hero image#

One original can have several purposeful renditions:

Component	Suggested goal	Example variant type
Product card	Small landscape image for a grid	`card`
Blog thumbnail	Small square preview	`thumbnail`
Product detail	Medium, detailed image	`medium`
Marketing hero	Wide image with a deliberate crop	`hero`

Do not rely on CSS width alone to make a file lighter. A browser still downloads the source URL it is given. Use a fitted media rendition when a component consistently needs a smaller asset.

Focal point: useful metadata, not automatic cropping#

The editor lets you save a focal point, such as a person's face or a product. This is useful editorial information, but it has an important current limitation:

it is stored on the media item;
it is not returned by the standard delivery media response; and
it does not direct the automatic generated variants.

For a guaranteed crop today, use the crop tool and save the result as a named variant or new asset. Do not assume every frontend or generated variant will honor a focal point.

How the processing endpoint works#

This is usually handled by the Media Library UI, but developers integrating an admin tool can use the same operation. It accepts crop coordinates in source-image pixels and saves either a variant or a new asset.

Example processing request

{
  "crop": { "x": 160, "y": 80, "width": 1920, "height": 1080 },
  "resize": { "width": 1600, "height": 900, "keepAspectRatio": true },
  "rotation": 0,
  "flipHorizontal": false,
  "flipVertical": false,
  "format": "webp",
  "quality": 85,
  "saveMode": "variant",
  "variantType": "hero"
}

The request is sent to:

Code

POST /api/admin/websites/{websiteId}/media/{mediaId}/process-image

It needs authenticated Media Library permissions. Keep this administration API behind an authenticated server or admin application; it is not a public frontend route.

Quality checklist#

Start with an original that is sharp enough for its largest planned use.
Crop around the subject, not only the center of the image.
Check that text placed over an image remains readable.
Provide meaningful alt text in the media metadata.
Test the final component on a narrow mobile viewport and a large screen.
Keep any manually created variant name meaningful and predictable for your team.

For automatic and manually named renditions, see Variants.

Image Processing