> ## 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.

# Customizing media URLs

> Understand ButterCMS CDN URLs, set up custom URL redirects, and implement image transformations for media assets.

{/* /SOURCE */}

### CDN & performance

All stored files in your application are available over the ButterCMS CDN, making it fast for your customers to download those assets as needed.

#### CDN benefits

* **Global Distribution** - Content served from edge locations worldwide
* **Automatic Caching** - Reduced load times for repeat visits
* **High Availability** - Reliable image delivery
* **SSL/HTTPS** - Secure image serving

#### CDN URL structure

```
https://cdn.buttercms.com/[file-identifier]
```

Example:

```
https://cdn.buttercms.com/Lvv0MCF0QhCoKLSuEJzD
```

## Understanding CDN URLs

All files you upload to your ButterCMS account will have a ButterCMS CDN URL. Files in the Media Library are assigned a random CDN URL slug so that each asset has its own unique URL.

### Example URLs

| Type                  | Example                                                 |
| --------------------- | ------------------------------------------------------- |
| **ButterCMS CDN URL** | `https://cdn.buttercms.com/Cw5z1qzSq5qtVMCbUDwQ`        |
| **Your desired URL**  | `https://mywebsite.com/HeadlessCMSvsTraditionalCMS.pdf` |

<Info>
  A URL on your site (e.g. `https://mywebsite.com/HeadlessCMSvsTraditionalCMS.pdf`) cannot link to a file in ButterCMS (e.g. `https://cdn.buttercms.com/Cw5z1qzSq5qtVMCbUDwQ`) since that asset resides on your domain. If you want to redirect a URL to an asset stored in your ButterCMS media library, you'll need to set up a URL route in your web application that is hardcoded to load the asset from ButterCMS.
</Info>

## Setting up custom URL redirects

If you want to set up multiple redirects for ButterCMS media assets, follow these steps:

### Step 1: create a resources Collection

Create a "Resources" Collection in ButterCMS with:

* A **Name** short text field
* A **Resource** media field

<Accordion title="Example Collection Structure">
  | Field Name | Field Type | Purpose                            |
  | ---------- | ---------- | ---------------------------------- |
  | Name       | Short Text | URL-friendly slug for the resource |
  | Resource   | Media      | The actual file to serve           |
</Accordion>

### Step 2: add a route in your application

Create a route that matches your desired URL pattern, for example:

```
mywebsite.com/files/<resource-name>/
```

### Step 3: query the Collection

Look up the resource by slug (or name) in your Resources collection.

```javascript theme={null}
// Example: Fetching resource from collection
const butter = require('buttercms')('your-api-key');

async function getResource(resourceName) {
  const response = await butter.content.retrieve(['resources'], {
    'fields.name': resourceName
  });
  return response.data.data.resources[0];
}

// In your route handler
app.get('/files/:resourceName', async (req, res) => {
  const resource = await getResource(req.params.resourceName);
  res.redirect(resource.resource); // Redirects to CDN URL
});
```

### Step 4: proxy or redirect to the asset

Redirect users to the CDN URL (recommended), or proxy the response through your app if you need to add headers or access controls.

## Image URL transformations

ButterCMS integrates with Filestack's Image API, allowing you to transform images by modifying the URL. This gives you powerful optimization capabilities without changing the original file.

### URL structure

Processing tasks can be added to any CDN URL. Tasks follow this structure:

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

Multiple tasks can be chained by separating them with forward slashes:

```
https://cdn.buttercms.com/TASK1=option:value/TASK2=option:value/FILE_ID
```

### Common transformations

| Task       | Example                       | Description                   |
| ---------- | ----------------------------- | ----------------------------- |
| **resize** | `resize=height:300`           | Resize to 300px height        |
| **resize** | `resize=width:800`            | Resize to 800px width         |
| **resize** | `resize=width:800,height:600` | Resize to specific dimensions |
| **crop**   | `crop=dim:[x,y,width,height]` | Crop to specific area         |
| **rotate** | `rotate=deg:90`               | Rotate by degrees             |
| **flip**   | `flip`                        | Flip image vertically         |
| **flop**   | `flop`                        | Flip image horizontally       |

<Tip>
  To preserve aspect ratio, specify only width **or** height (for example, `resize=width:800`). If you set both width and height, the image is resized to those exact dimensions.
</Tip>

### Examples

**Original URL:**

```
https://cdn.buttercms.com/Lvv0MCF0QhCoKLSuEJzD
```

**Resize to 300px height:**

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

**Resize to 800px width:**

```
https://cdn.buttercms.com/resize=width:800/Lvv0MCF0QhCoKLSuEJzD
```

**Multiple transformations:**

```
https://cdn.buttercms.com/resize=width:800/rotate=deg:90/Lvv0MCF0QhCoKLSuEJzD
```

<Tip>
  Using URL transformations creates a new optimized version of the image on the CDN, improving page load times without modifying your original file.
</Tip>

For more advanced image transformations, refer to the Filestack Processing API documentation.

## Best practices

<CardGroup cols={2}>
  <Card title="Cache Transformed Images" icon="database">
    URL transformations are cached on the CDN, so subsequent requests are fast
  </Card>

  <Card title="Responsive Images" icon="mobile">
    Use URL parameters to serve different image sizes for different screen sizes
  </Card>

  <Card title="Original Backup" icon="shield">
    Your original files are always preserved; transformations create new versions
  </Card>

  <Card title="Descriptive Names" icon="file-signature">
    Use SEO-friendly slugs in your Resources collection for readable URLs
  </Card>
</CardGroup>