Pre-defined aliases

Transform your images efficiently using predefined transformation aliases. Instead of specifying complex transformation parameters every time, you can create named presets that combine multiple settings into a single, easy-to-use alias.

What are transformation aliases?

Transformation aliases are named presets that bundle multiple image transformation settings together. Rather than manually specifying width, height, format, quality, and other parameters for each request, you can define commonly used combinations and reference them by name.

Example: Instead of calling:

/sources/gallery/media/photo.jpg?width=300&height=300&format=WEBP&quality=85&mode=FILL

You can create a “thumbnail” alias and simply use:

/sources/gallery/media/photo.jpg?alias=thumbnail

Benefits of using aliases

• Consistency: Ensure all images use the same transformation settings across your application
• Simplicity: Reduce complex URLs to simple, readable aliases
• Maintainability: Update transformation settings in one place rather than throughout your codebase
• Performance: Optimize caching by standardizing transformation parameters

Creating transformation aliases

See our guide that will show you step by step how to create your first alias

Using aliases in requests

Basic usage

Add the alias parameter to your media URLs:

GET /sources/{sourceId}/media/{filePath}?alias=thumbnail

Alias shortcuts:

• Use a instead of alias: ?a=thumbnail

Combining with other parameters

Don’t combine params with aliases

You cannot combine other parameters with aliases.

# This won't work
/sources/gallery/media/photo.jpg?alias=thumbnail&format=PNG

If you decide to combine aliases with extra transformations params, all extra params will be ignored.

Security considerations

Restricting to known aliases

If you would like to allow only aliased transformations, you can do so in security page. Turning that option on will allow only transformation requests with aliases, and anything else will return an error.

When enabled:

• ✅ ?alias=thumbnail (if defined) - Allowed
• ❌ ?width=500&height=300 - Rejected
• ❌ ?alias=undefined-alias - Rejected

This prevents clients from requesting arbitrary transformations and helps control resource usage.

Best practices

Naming conventions

Establish consistent naming patterns:

• Size-based: small, medium, large, xl
• Use case: thumbnail, hero, gallery, avatar
• Device-based: mobile, tablet, desktop
• Ratio-based: square, wide, portrait

Troubleshooting

Common issues

Alias not found (404 error)

• Verify the alias exists
• Check alias name spelling and character restrictions

Unexpected transformation results

• Review parameter priority (URL params override alias settings)
• Verify transformation settings in the alias definition
• Check for conflicting parameters in the URL

For complete API documentation, see the Media Settings API reference and Media Transformation API reference.