Setting the file. One moment.
Subchapter 3.16
references/images/overview.mdMarkdown4 KBView on GitHub
The Images API transforms images on-the-fly via URL parameters. No authentication required.
https://images.ctfassets.nethttps://images.eu.ctfassets.netNo authentication is needed. The URL from an asset’s file.url field already points to this host.
https://images.ctfassets.net/{space_id}/{asset_id}/{unique_token}/{filename}?{parameters}The full URL is returned in asset responses as fields.file.url (prefixed with //).
# Set width (height auto-scales)
...?w=300
# Set height (width auto-scales)
...?h=200
# Set both (behavior depends on fit mode)
...?w=300&h=200Maximum dimension: 4000px.
Control how the image fits within the specified dimensions:
| Mode | Description |
|---|---|
pad | Resize to fit within dimensions, pad remaining space with background color |
fill | Resize to fill dimensions, crop overflow |
scale | Resize to fit within dimensions, no cropping or padding |
crop | Crop to exact dimensions from center (or focus area) |
thumb | Thumbnail — smart crop using focus area detection |
# Pad with white background
...?w=300&h=200&fit=pad&bg=rgb:ffffff
# Fill (crop overflow)
...?w=300&h=200&fit=fill
# Scale to fit
...?w=300&fit=scale
# Crop from center
...?w=300&h=200&fit=crop
# Smart thumbnail
...?w=150&h=150&fit=thumb&f=faceControl the focal point for fit=crop, fit=fill, and fit=thumb:
| Value | Description |
|---|---|
center | Center of image (default) |
top | Top edge |
right | Right edge |
bottom | Bottom edge |
left | Left edge |
top_right | Top-right corner |
top_left | Top-left corner |
bottom_right | Bottom-right corner |
bottom_left | Bottom-left corner |
face | Detected face (auto) |
faces | All detected faces (auto) |
# Crop focusing on faces
...?w=300&h=300&fit=thumb&f=faces
# Crop from top
...?w=800&h=400&fit=crop&f=topConvert between image formats:
# Convert to WebP
...?fm=webp
# Convert to AVIF
...?fm=avif
# Convert to PNG
...?fm=png
# Convert to JPEG
...?fm=jpg
# Convert to progressive JPEG
...?fm=jpg&fl=progressive
# Convert to 8-bit PNG
...?fm=png&fl=png8Supported formats: jpg, png, webp, gif, avif.
Control JPEG/WebP/AVIF compression quality (1-100):
# 80% quality (good balance of size and visual quality)
...?q=80
# Lower quality, smaller file
...?q=50
# High quality
...?q=95Default quality varies by format. Only applies to jpg, webp, and avif.
# Round corners (max: half of smallest dimension for circle)
...?r=20
# Full circle (use with equal w and h)
...?w=200&h=200&fit=fill&r=max# RGB hex
...?fit=pad&w=300&h=200&bg=rgb:ff0000
# With transparency (for PNG)
...?fit=pad&w=300&h=200&bg=rgb:00000000Chain multiple transformations:
# Responsive hero image: 800px wide, WebP, 80% quality
https://images.ctfassets.net/{space}/{id}/{token}/hero.jpg?w=800&fm=webp&q=80
# Thumbnail: 150x150, smart crop on faces, WebP
https://images.ctfassets.net/{space}/{id}/{token}/photo.jpg?w=150&h=150&fit=thumb&f=faces&fm=webp&q=80
# Padded product image: 400x400, white background, PNG
https://images.ctfassets.net/{space}/{id}/{token}/product.png?w=400&h=400&fit=pad&bg=rgb:ffffff
# Avatar circle: 100x100
https://images.ctfassets.net/{space}/{id}/{token}/avatar.jpg?w=100&h=100&fit=fill&f=face&r=max&fm=webpq=80 is usually sufficientfit=fill for fixed-size containersf=faces for profile photos and portraitsw values per breakpoint