Documentation

Learn how to transform images with simple URL parameters. Our pipeline-based system processes transformations in the order you specify.

Get Started API Reference

Quick Start

Get started in minutes

Transform your first image in 4 simple steps.

Create Account

Create Source

Connect your S3 bucket, Cloudflare R2 storage, or any public URL as an image source.

Get Subdomain

Your images are served from {subdomain}.xform.media

Start Transforming

Add query parameters to any image URL to transform on the fly.

Your first transformation

Resize to 800x600, crop to cover, convert to WebP at 85% quality:

https://my-images.xform.media/photos/hero.jpg?w=800&h=600&fit=cover&f=webp&q=85

Core Concept

Pipeline-based transformations

Understanding how parameters are processed is key to getting the results you want.

xform processes query parameters in the order they appear in the URL, like a pipeline. Each transformation is applied sequentially, allowing you to chain operations in a predictable way.

Parameter Grouping

Some related parameters are automatically grouped together into single operations:

Resize parameters (w, h, fit, p) are combined into one resize operation
Modulate parameters (brightness, saturation, hue) are combined into one color adjustment

When a non-grouped parameter is encountered, any pending grouped operations are executed first.

Interactive Pipeline Demo

Click parameters to add them to the URL. Watch how they get grouped and ordered in the pipeline.

Available Parameters

Pipeline Execution Order

Add parameters above to see how they're processed

Legend

Resize (grouped)

Modulate (grouped)

Blur/Sharpen

Rotate/Flip

Format/Quality

Example: Multi-step pipeline

https://my-images.xform.media/image.jpg?w=800&blur=3&rotate=90&grayscale=true&f=webp

Execution order:

Resize to 800px wide
Apply blur (sigma=3)
Rotate 90 degrees
Convert to grayscale
Output as WebP

Example: Extract then transform

https://my-images.xform.media/image.jpg?e=100,200,400,300&w=200&blur=2

Execution order:

Extract 400x300 region starting at (100,200)
Resize to 200px wide
Apply blur

API Reference

Transformation parameters

Complete reference for all available query parameters.

Resize & Crop

Parameter	Alias	Example	Description
`width`	`w`	`w=400`	Width in pixels (1-8192)
`height`	`h`	`h=300`	Height in pixels (1-8192)
`fit`	-	`fit=cover`	cover, contain, fill, inside, outside
`position`	`p`	`p=top-left`	Crop anchor point
`extract`	`e`	`e=10,20,300,400`	Pixel-precise crop (left,top,width,height)

Rotation & Flip

Parameter	Alias	Example	Description
`rotate`	`r`	`r=90`	Rotate 0, 90, 180, or 270 degrees
`flip`	-	`flip=true`	Mirror vertically
`flop`	-	`flop=true`	Mirror horizontally

Effects & Filters

Parameter	Alias	Example	Description
`blur`	`b`	`b=5`	Gaussian blur (sigma 0.3-1000)
`sharpen`	`s`	`s=true`	Sharpen image
`brightness`	-	`brightness=1.2`	Brightness multiplier (1.0 = no change)
`saturation`	-	`saturation=1.5`	Saturation multiplier (1.0 = no change)
`hue`	-	`hue=45`	Hue shift (0-360 degrees)
`grayscale`	-	`grayscale=true`	Convert to grayscale

Format & Quality

Parameter	Alias	Example	Description
`format`	`f`	`f=webp`	jpeg, png, webp, avif, gif, tiff
`quality`	`q`	`q=80`	Compression quality (1-100, default: 80)

Metadata Extraction

Parameter	Alias	Example	Description
`metadata`	-	`?metadata`	Returns image dimensions, format, channels
`colors`	-	`?colors`	Returns dominant + vibrant color palette
`base64`	-	`?base64`	Returns base64-encoded thumbnail (LQIP)
`exif`	-	`?exif`	Returns camera/GPS EXIF data (if enabled)
`meta`	-	`?meta=true`	Returns all metadata combined

Reference

Position values

Control where the image is anchored during cropping with the position parameter.

Basic Positions

toprightbottomleftcenter

Corner Positions

top-lefttop-rightbottom-leftbottom-right

Cardinal Positions

northsoutheastwestnortheastnorthwestsoutheastsouthwest

Smart Positioning

entropy

Focus on the busiest area of the image (high detail regions).

attention

Focus on prominent features like faces or objects.

Note: You can use hyphens or underscores interchangeably. For example, p=top-left and p=top_left are equivalent.

Reference

Fit values

Control how images are resized to fit within the specified dimensions.

cover

Fill dimensions, crop excess (default)

contain

Fit within dimensions, may letterbox

fill

Stretch to fill (distorts aspect ratio)

inside

Resize to fit inside dimensions

outside

Resize to cover dimensions minimum

Integration

Source configuration

Configure your image sources for optimal performance.

Supported Storage Providers

Amazon S3

Standard S3 buckets with IAM credentials.

Cloudflare R2

S3-compatible storage with zero egress fees.

Public URL

Any publicly accessible web URL as an image source.

Required Credentials

Bucket name - Your storage bucket identifier
Region - AWS region or R2 account ID
Access Key ID - IAM or R2 API token
Secret Access Key - Associated secret

Security tip: Only provide credentials with read-only permissions. xform only needs to read your images, never write or delete.

Your Access Key ID and Secret Access Key are encrypted at rest and never exposed in logs or API responses.

Optional Settings

Cache settings - Configure max-age and s-maxage for CDN
EXIF extraction - Enable/disable EXIF metadata extraction

Performance

Caching

Transformed images are cached at the edge for fast delivery.

xform automatically caches transformed images using CDN edge caching. Cache headers are configured per-source:

Cache-Control: public, max-age=31536000, s-maxage=31536000

max-age

Browser cache duration. Configure this based on how often your images change.

s-maxage

CDN cache duration. Set this higher for longer edge caching.

Responses

Response types

xform returns either transformed images or JSON metadata.

Image Response (default)

When you request a transformation without metadata parameters, xform returns the transformed image with the appropriate Content-Type header.

Returns a WebP image:

https://my-images.xform.media/photo.jpg?w=400&f=webp

JSON Metadata Response

When you include metadata parameters, xform returns a JSON response with the requested data.

Returns JSON with dimensions and color palette:

https://my-images.xform.media/photo.jpg?metadata&colors

Example JSON Response

{
  "metadata": {
    "width": 1920,
    "height": 1080,
    "format": "jpeg",
    "channels": 3,
    "hasAlpha": false
  },
  "colors": {
    "dominant": { "rgb": [64, 128, 192], "hex": "#4080c0" },
    "vibrant": { "rgb": [48, 160, 255], "hex": "#30a0ff" },
    "palette": [...]
  }
}

Troubleshooting

Error handling

Common HTTP status codes and their meanings.

Status Code	Meaning
`400`	Invalid parameters - check your query string
`403`	Source suspended - contact support
`404`	Image not found at the specified path
`500`	Processing error - try again or contact support

Limits

Technical constraints

Maximum values and limits for transformation parameters.

8192px

Max dimension

1-100

Quality range

0.3-1000

Blur sigma

90/180/270

Rotation degrees

Supported Output Formats

jpegjpgpngwebpavifgiftiff