Every application with user uploads eventually needs image transformation. Thumbnails for listings, responsive images for different devices, compressed versions for faster loading.
The traditional approach? Generate and store multiple versions of every image. That means more storage costs, more complexity, and more things that can go wrong.
We built a better way.
Transform on Request
Centrali's render endpoint now accepts transformation parameters. Upload an image once, request it in any size or format.
# Original image
GET /workspace/my-workspace/api/v1/render/abc123
# Resize to 200px width
GET /workspace/my-workspace/api/v1/render/abc123?width=200
# Both dimensions (fits within, maintains aspect ratio)
GET /workspace/my-workspace/api/v1/render/abc123?width=800&height=600
# Compress JPEG
GET /workspace/my-workspace/api/v1/render/abc123?format=jpeg&quality=60
# Convert to WebP
GET /workspace/my-workspace/api/v1/render/abc123?format=webpParameters
| Parameter | Type | Default | Description |
|---|---|---|---|
width | int | - | Target width in pixels (max 4096) |
height | int | - | Target height in pixels (max 4096) |
quality | int | 85 | JPEG quality 1-100 |
format | string | original | Output: jpeg, png, or webp |
Use Cases
Thumbnails
Generate thumbnails for product galleries, user avatars, and content previews:
<!-- Product thumbnail -->
<img src="https://api.centrali.io/workspace/store/api/v1/render/prod123?width=150" />
<!-- Full-size on click -->
<img src="https://api.centrali.io/workspace/store/api/v1/render/prod123" />Responsive Images
Serve appropriately sized images for different devices:
<picture>
<source
media="(max-width: 480px)"
srcset="https://api.centrali.io/.../render/hero?width=480&format=webp"
/>
<source
media="(max-width: 1024px)"
srcset="https://api.centrali.io/.../render/hero?width=1024&format=webp"
/>
<img
src="https://api.centrali.io/.../render/hero?width=1920"
alt="Hero image"
/>
</picture>Bandwidth Optimization
Reduce bandwidth for mobile users with lower quality and modern formats:
const isMobile = window.innerWidth < 768;
const imageUrl = new URL(`https://api.centrali.io/.../render/${imageId}`);
if (isMobile) {
imageUrl.searchParams.set('width', '600');
imageUrl.searchParams.set('quality', '70');
imageUrl.searchParams.set('format', 'webp');
}
document.getElementById('hero').src = imageUrl.toString();Email Images
Create email-safe images with guaranteed dimensions:
const emailImageUrl = `${renderUrl}?width=600&format=jpeg&quality=80`;
const html = api.renderTemplate(emailTemplate, {
productImage: emailImageUrl,
// ...
});Supported Formats
Input formats:
- JPEG / JPG
- PNG
- WebP
- GIF (converted to PNG on output)
- BMP
- TIFF
Output formats:
- JPEG (with quality control)
- PNG
- WebP
Behavior Notes
- Aspect ratio is always preserved. Specify one dimension and the other scales proportionally.
- Both dimensions means the image fits within those bounds—it won't stretch or distort.
- Quality only applies to JPEG output.
- Non-images (PDFs, documents) are returned unchanged.
- Invalid parameters fall back to original image.
Example: E-commerce Product Page
function ProductGallery({ images }) {
const [selected, setSelected] = useState(0);
return (
<div>
{/* Main image - large, high quality */}
<img
src={`${images[selected]}?width=800&format=webp&quality=90`}
alt="Product"
/>
{/* Thumbnails - small, compressed */}
<div className="thumbnails">
{images.map((img, i) => (
<img
key={i}
src={`${img}?width=100&format=webp&quality=70`}
onClick={() => setSelected(i)}
alt={`Thumbnail ${i + 1}`}
/>
))}
</div>
</div>
);
}Performance Considerations
- Transformations are computed on request, so first requests take slightly longer
- Subsequent requests benefit from CDN caching
- For extremely high-traffic images, consider caching the transformed URL client-side
Try It Now
Image transformation is available now on all workspaces. Just append the parameters to your render URLs.
Check the storage documentation for more details.