# Image optimization

> Optimize Cevoid CDN image URLs for responsive storefronts and different display densities.

Breadcrumb: Storefront API › Images · Updated: 2026-10-17
Docs index: https://docs.cevoid.com/developers/llms.txt

Use this page when you fetch Cevoid image URLs and want to render them efficiently in a storefront. For gallery and card behavior, see [Widget](https://docs.cevoid.com/developers/widget.md). To fetch posts and their image URLs, see [Custom UGC experiences](https://docs.cevoid.com/developers/storefront-api/custom-ugc.md).

## When to use this

Use image optimization when:

- you fetch raw Cevoid image URLs from the Storefront API
- you render those images in a custom storefront UI
- you want smaller responsive images instead of the original full-size asset

Cevoid image URLs return the original image by default. Add the `class` query parameter when you want a pre-optimized size from the CDN.

## Quickstart

1. Fetch or receive the original Cevoid image URL.
2. Add `?class=<size>` to request an optimized width.
3. Use the optimized URL in your storefront markup.
4. Add `srcset` only when you need responsive behavior across breakpoints.

Example:

```html
<img
  src="https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=640"
  alt="User generated content"
/>
```

## Available image classes

The Cevoid CDN provides several pre-optimized image sizes:

| Class | Width (pixels) | Use case |
| --- | --- | --- |
| `original` | Full resolution | High-quality displays, print |
| `1080` | 1080px | Desktop hero images, large displays |
| `750` | 750px | Tablet landscape, desktop cards |
| `640` | 640px | Tablet portrait, large mobile |
| `480` | 480px | Mobile landscape |
| `400` | 400px | Mobile portrait, thumbnails |
| `320` | 320px | Small mobile screens |
| `240` | 240px | Thumbnail grids |
| `160` | 160px | Small thumbnails, avatars |

## Example: transform an API image URL

When you fetch posts from the [Storefront API](https://docs.cevoid.com/developers/storefront-api.md), each post's `media.url` holds the original image URL:

```json
{
  "id": "pst_summerlook",
  "type": "IMAGE",
  "media": {
    "url": "https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT",
    "aspect_ratio": 0.8
  }
}
```

For `VIDEO` posts, `media.url` is the video file. Add the `class` parameter to the preview image in `media.thumbnail_url` instead.

Transform the URL by adding the `class` parameter:

```javascript
const originalUrl = 'https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT'
const optimizedUrl = `${originalUrl}?class=640`

console.log(optimizedUrl)
```

Result:

```text
https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=640
```

## Performance guidance

### Choose the right size

> [!TIP]
> Select the image class that best matches your display requirements. Using unnecessarily large images wastes bandwidth and slows loading times.

### Responsive images

Use different image classes for different screen sizes:

```html
<img
  src="https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=320"
  srcset="
    https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=320 320w,
    https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=640 640w,
    https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=1080 1080w"
  sizes="(max-width: 320px) 320px, (max-width: 640px) 640px, 1080px"
  alt="User generated content"
/>
```

### Pick the nearest useful class

```javascript
function getOptimizedImageUrl(originalUrl, targetWidth) {
  const imageClasses = [160, 240, 320, 400, 480, 640, 750, 1080]
  const bestClass = imageClasses.find((size) => size >= targetWidth) || 'original'

  return `${originalUrl}?class=${bestClass}`
}

const imageUrl = 'https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT'
const optimized = getOptimizedImageUrl(imageUrl, 400)
```

## Best practices

### 1. Match image size to container

Always choose an image class that matches or slightly exceeds your container's display size:

```css
.image-container {
  width: 300px;
}
```

### 2. Consider display density

For high-density displays (Retina, etc.), use an image class that's 2x your container size:

```js
const containerWidth = 200;
const pixelRatio = window.devicePixelRatio || 1;
const targetWidth = containerWidth * pixelRatio;

const optimizedUrl = getOptimizedImageUrl(originalUrl, targetWidth);
```

### 3. Lazy loading

Combine image optimization with lazy loading for maximum performance:

```html
<img
  data-src="https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=640"
  class="lazy-load"
  alt="User generated content"
/>
```

### 4. Fallback strategy

Always have a fallback for when optimized images fail to load:

```js
function handleImageError(img) {
  const originalUrl = img.src.split('?')[0]
  img.src = originalUrl
}
```

```html
<img
  src="https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=640"
  onerror="handleImageError(this)"
  alt="User generated content"
/>
```

> [!NOTE]
> The Cevoid CDN automatically handles caching and global distribution of optimized images, ensuring fast loading times for users worldwide.

### 5. Preloading critical images

For above-the-fold images, consider preloading:

```html
<link rel="preload" as="image" href="https://cdn.cevoid.com/images/V1StGXR8_Z5jdHi6B-myT?class=1080">
```

> [!WARNING]
> Don't preload too many images as this can actually slow down initial page load. Only preload the most critical, above-the-fold images.

## Related articles

- [Storefront API](https://docs.cevoid.com/developers/storefront-api.md)
- [Cevoid widgets](https://docs.cevoid.com/developers/widget.md)

---

Canonical: https://docs.cevoid.com/developers/storefront-api/images