> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Image transformations

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

## Overview

ButterCMS integrates with [Filestack](https://www.filestack.com/) 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:**

```bash theme={null}
# 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:**

```bash theme={null}
# 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:

<Note>
  Face detection is provided by Filestack's processing API. Feature availability may vary by plan.
</Note>

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
https://cdn.buttercms.com/output=format:webp/FILE_ID
```

## Filters & effects

### Blur

```
blur=amount:AMOUNT
```

Amount: 0-20 (higher = more blur)

```bash theme={null}
https://cdn.buttercms.com/blur=amount:5/FILE_ID
```

### Sharpen

```
sharpen=amount:AMOUNT
```

Amount: 1-10 (higher = more sharpening)

```bash theme={null}
https://cdn.buttercms.com/sharpen=amount:10/FILE_ID
```

### Grayscale

```
monochrome
```

```bash theme={null}
https://cdn.buttercms.com/monochrome/FILE_ID
```

### Sepia

```
sepia=tone:AMOUNT
```

Tone: 0-100 (percentage of sepia effect)

```bash theme={null}
https://cdn.buttercms.com/sepia=tone:80/FILE_ID
```

### Brightness & contrast

```
enhance
```

Auto-enhance brightness and contrast:

```bash theme={null}
https://cdn.buttercms.com/enhance/FILE_ID
```

## Watermarks & overlays

<Note>
  Watermark functionality is provided by Filestack's processing API. Feature availability may vary by [plan](/support/account-management/billing-plans/plan-comparison).
</Note>

### 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:**

```bash theme={null}
https://cdn.buttercms.com/watermark=file:WATERMARK_ID,position:bottom/FILE_ID
```

## Common transformation recipes

### Thumbnail (square)

```bash theme={null}
https://cdn.buttercms.com/resize=width:150,height:150,fit:crop/FILE_ID
```

### Hero image (optimized)

```bash theme={null}
https://cdn.buttercms.com/resize=width:1920/quality=value:85/output=format:webp/FILE_ID
```

### Avatar with face detection

```bash theme={null}
https://cdn.buttercms.com/resize=width:100,height:100,fit:crop,align:faces/FILE_ID
```

### Blog featured image

```bash theme={null}
https://cdn.buttercms.com/resize=width:1200/quality=value:80/FILE_ID
```

### Card image

```bash theme={null}
https://cdn.buttercms.com/resize=width:400,height:250,fit:crop/FILE_ID
```

## Code examples

<CodeGroup>
  ```javascript JavaScript theme={null}
  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 }
    }
  );
  ```

  ```python Python theme={null}
  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}
      }
  )
  ```
</CodeGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Responsive Images" icon="mobile" href="../image-api/responsive-images">
    Generate responsive images
  </Card>

  <Card title="Security" icon="shield" href="../image-api/security-authentication">
    Secure your images
  </Card>

  <Card title="Media Library" icon="photo-film" href="/create-content/media-management/media-library-overview">
    Media management
  </Card>

  <Card title="Image Compression" icon="bolt" href="/create-content/media-management/automatic-image-compression-webp">
    Automatic optimization
  </Card>
</CardGroup>