Image transformations

Complete reference for ButterCMS Image API transformation parameters including resize, crop, filters, and effects.

Overview

ButterCMS integrates with Filestack to provide powerful image transformation capabilities through URL parameters. Transform images on-the-fly without modifying originals—perfect for responsive images, thumbnails, and optimized delivery.

Key benefits

• No Pre-processing: Transform images at request time
• CDN Cached: Transformed images are cached globally
• Original Preserved: Original files remain unchanged
• Chainable: Combine multiple transformations

URL structure

All images in ButterCMS have a CDN URL. Add transformation tasks before the file ID:

https://cdn.buttercms.com/TASK=option:value/FILE_ID

Original URL:

https://cdn.buttercms.com/Lvv0MCF0QhCoKLSuEJzD

With Transformation:

https://cdn.buttercms.com/resize=height:300/Lvv0MCF0QhCoKLSuEJzD

Chaining transformations

Combine multiple transformations with forward slashes:

https://cdn.buttercms.com/resize=width:800/rotate=deg:90/quality=value:80/FILE_ID

Resize transformations

Basic resize

Parameter	Description	Example
width	Target width in pixels	resize=width:800
height	Target height in pixels	resize=height:600
width,height	Both dimensions	resize=width:800,height:600

Resize options

Option	Values	Description
fit	clip, crop, scale, max	How to fit the image
align	center, top, bottom, left, right, faces	Alignment for crop/fit

Examples:

# Resize to max width, maintain aspect ratio
https://cdn.buttercms.com/resize=width:800/FILE_ID

# Resize and crop to exact dimensions
https://cdn.buttercms.com/resize=width:400,height:300,fit:crop/FILE_ID

# Resize with face detection alignment
https://cdn.buttercms.com/resize=width:200,height:200,fit:crop,align:faces/FILE_ID

Fit modes

Mode	Behavior
clip	Resize to fit within bounds, maintain aspect ratio (default)
crop	Resize and crop to exact dimensions
scale	Stretch to exact dimensions (may distort)
max	Resize to not exceed bounds

Crop transformations

Basic crop

crop=dim:[x,y,width,height]

Example:

# Crop starting at (100,50) with 400x300 dimensions
https://cdn.buttercms.com/crop=dim:[100,50,400,300]/FILE_ID

Smart crop (face detection)

Automatically crop around detected faces:

Face detection is provided by Filestack’s processing API. Feature availability may vary by plan.

https://cdn.buttercms.com/resize=width:200,height:200,fit:crop,align:faces/FILE_ID

Rotation & flip

Rotate

rotate=deg:DEGREES

Value	Description
90	Rotate 90° clockwise
180	Rotate 180°
270	Rotate 270° clockwise
exif	Auto-rotate based on EXIF data

Examples:

https://cdn.buttercms.com/rotate=deg:90/FILE_ID
https://cdn.buttercms.com/rotate=deg:exif/FILE_ID

Flip

Task	Description
flip	Flip vertically
flop	Flip horizontally

Examples:

https://cdn.buttercms.com/flip/FILE_ID
https://cdn.buttercms.com/flop/FILE_ID

Quality & format

Quality compression

Control JPEG/WebP quality (0-100):

quality=value:QUALITY

Example:

https://cdn.buttercms.com/quality=value:80/FILE_ID

Format conversion

Convert between image formats:

output=format:FORMAT

Format	Use Case
jpg	Photos, complex images
png	Graphics with transparency
webp	Modern browsers, best compression
gif	Animations

Example:

https://cdn.buttercms.com/output=format:webp/FILE_ID

Filters & effects

Blur

blur=amount:AMOUNT

Amount: 0-20 (higher = more blur)

https://cdn.buttercms.com/blur=amount:5/FILE_ID

Sharpen

sharpen=amount:AMOUNT

Amount: 1-10 (higher = more sharpening)

https://cdn.buttercms.com/sharpen=amount:10/FILE_ID

Grayscale

monochrome

https://cdn.buttercms.com/monochrome/FILE_ID

Sepia

sepia=tone:AMOUNT

Tone: 0-100 (percentage of sepia effect)

https://cdn.buttercms.com/sepia=tone:80/FILE_ID

Brightness & contrast

enhance

Auto-enhance brightness and contrast:

https://cdn.buttercms.com/enhance/FILE_ID

Watermarks & overlays

Watermark functionality is provided by Filestack’s processing API. Feature availability may vary by plan.

Basic watermark

watermark=file:WATERMARK_FILE_ID,position:POSITION

Position	Description
top	Top center
bottom	Bottom center
left	Left center
right	Right center
center	Center
[top,left]	Specific coordinates

Example:

https://cdn.buttercms.com/watermark=file:WATERMARK_ID,position:bottom/FILE_ID

Common transformation recipes

Thumbnail (square)

https://cdn.buttercms.com/resize=width:150,height:150,fit:crop/FILE_ID

Hero image (optimized)

https://cdn.buttercms.com/resize=width:1920/quality=value:85/output=format:webp/FILE_ID

Avatar with face detection

https://cdn.buttercms.com/resize=width:100,height:100,fit:crop,align:faces/FILE_ID

Blog featured image

https://cdn.buttercms.com/resize=width:1200/quality=value:80/FILE_ID

Card image

https://cdn.buttercms.com/resize=width:400,height:250,fit:crop/FILE_ID

Code examples

JavaScript

function getTransformedUrl(originalUrl, transformations) {
  // Extract file ID from URL
  const fileId = originalUrl.split('/').pop();

  // Build transformation string
  const transforms = Object.entries(transformations)
    .map(([key, value]) => {
      if (typeof value === 'object') {
        const params = Object.entries(value)
          .map(([k, v]) => `${k}:${v}`)
          .join(',');
        return `${key}=${params}`;
      }
      return key;
    })
    .join('/');

  return `https://cdn.buttercms.com/${transforms}/${fileId}`;
}

// Usage
const heroUrl = getTransformedUrl(
  'https://cdn.buttercms.com/abc123',
  {
    resize: { width: 1200, height: 600, fit: 'crop' },
    quality: { value: 85 }
  }
);

def get_transformed_url(original_url, transformations):
    # Extract file ID
    file_id = original_url.split('/')[-1]

    # Build transformation string
    transforms = []
    for key, value in transformations.items():
        if isinstance(value, dict):
            params = ','.join(f'{k}:{v}' for k, v in value.items())
            transforms.append(f'{key}={params}')
        else:
            transforms.append(key)

    transform_string = '/'.join(transforms)
    return f'https://cdn.buttercms.com/{transform_string}/{file_id}'

# Usage
hero_url = get_transformed_url(
    'https://cdn.buttercms.com/abc123',
    {
        'resize': {'width': 1200, 'height': 600, 'fit': 'crop'},
        'quality': {'value': 85}
    }
)

Next steps

Responsive Images

Generate responsive images

Security

Secure your images

Media Library

Media management

Image Compression

Automatic optimization