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}.staging.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.staging.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.staging.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.staging.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

Social Sharing

OG Image Generation

Generate beautiful Open Graph images for social media sharing on the fly.

xform can automatically generate Open Graph (OG) images for your content. These images appear when your links are shared on social media platforms like Twitter, Facebook, LinkedIn, and Slack.

OG images are generated using your source image as the background, with customizable overlays for logos, titles, and descriptions. All styling is configured in the admin dashboard.

Dynamic Backgrounds

Use any image from your source as the background, or upload a custom background image.

Custom Text Overlays

Add titles and descriptions with customizable fonts, colors, and positioning.

Brand Consistency

Add your logo and apply consistent styling across all generated OG images.

Setup

Configuring OG Images

Configure your OG image settings in the admin dashboard.

Background Options

Source Image

Uses the requested image as the background (default behavior).

Custom Background

Upload a static background image to use for all OG images.

Solid Color

Use a solid background color instead of an image.

Mask Overlay

Apply a semi-transparent overlay to improve text readability over complex backgrounds.

ColorOpacity

Logo Settings

Upload logo - PNG or SVG with transparency recommended
Position - Top-left, top-right, bottom-left, bottom-right
Size - Width and height in pixels

Text Styling

Font family - Choose from system fonts
Font size - Title and description sizes
Text color - Customize for readability
Position - X/Y coordinates for precise placement

Border

Optionally add a colored border around the OG image for brand recognition.

Implementation

Using OG Images

Generate OG images by adding query parameters to your image URLs.

OG Image Parameters

Parameter	Alias	Example	Description
`type`	-	`type=og`	Enables OG image generation mode
`title`	-	`title=My%20Title`	Main title text (URL-encoded)
`description`	-	`description=My%20desc`	Description text (URL-encoded)
`format`	`f`	`f=png`	Output format: png, jpeg, or webp (default: png)

Basic Example

Generate an OG image with title and description:

https://my-images.staging.xform.media/photos/hero.jpg?type=og&title=Welcome%20to%20Our%20Site&description=Discover%20amazing%20content

Without Source Image

Use the /og endpoint to generate OG images without specifying a source image. Uses your configured default background.

https://my-images.staging.xform.media/og?title=My%20Title&description=My%20description

Output Formats

OG images default to PNG for best quality, but you can specify other formats.

https://my-images.staging.xform.media/image.jpg?type=og&title=Hello&f=webp

HTML Meta Tags

Add these meta tags to your HTML to enable social sharing previews:

<meta property="og:image" content="https://{domain}/image.jpg?type=og&title=..." />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content="https://{domain}/image.jpg?type=og&title=..." />

Tip: OG images are generated at 1200x630 pixels by default, which is the recommended size for most social platforms.

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