Documentation

Everything you need to transform and deliver images with Image Foundry.

Quick Start

Get started in under 2 minutes:

1. Sign up from the dashboard and create a project
2. Add a storage source — connect your S3 bucket, R2, GCS, Azure, or any supported provider
3. Choose your URL style: ImageBoss (path-based) or Imgix (query params)
4. Start serving optimized images instantly:

https://img./my-source/width/800/format:auto/photo.jpg

https://my-source./photo.jpg?w=800&auto=format

Core Concepts

Sources

A source connects to a storage provider where your original images live. Each source has its own slug, URL mode (ImageBoss or Imgix), configuration, and usage tracking. You can have multiple sources per project.

Master Images

Master images are unique original images discovered by Image Foundry. When you request /photo.jpg?w=400 and /photo.jpg?w=800, that counts as 1 master image and 2 transformations. Master image counts help you understand the actual size of your image library vs. the number of URL variants being served.

URL Modes

Each source runs in one of two compatibility modes:

• ImageBoss — path-based operations: /source/operation/dimensions/options/image.jpg
• Imgix — query parameter operations: /source/image.jpg?w=400&h=300&fit=crop

Your Account

Sign Up & Log In

Create your account from the dashboard. Once logged in, you can create projects, add sources, configure custom domains, and view usage analytics — all from the dashboard.

Projects

A project groups your sources, domains, and usage together. You can create multiple projects to separate different applications or environments (e.g. production vs. staging).

API Keys

Each project has an API key for programmatic access (e.g. purging cache from your CI/CD pipeline). Find your API key in the project settings on the dashboard. You can rotate it at any time — the old key is immediately invalidated.

Amazon S3

Connect to any S3 bucket. Your IAM credentials need s3:GetObject permission.

Setup

1. In the dashboard, click Add Source and select Amazon S3
2. Enter your Bucket name and Region
3. Add your Access Key ID and Secret Access Key
4. Optionally set a Prefix to scope to a subfolder (e.g. images/)

S3-Compatible Endpoint

For MinIO or other S3-compatible services, enter the Endpoint URL and enable Force path-style. Force path-style uses endpoint/bucket/key addressing instead of bucket.endpoint/key — required by services that don't support virtual-hosted style DNS.

IAM Policy

Minimal permissions needed:

s3:GetObject    — on arn:aws:s3:::my-bucket/*
s3:ListBucket   — on arn:aws:s3:::my-bucket  (optional, for health checks)

Cloudflare R2

R2 is S3-compatible with zero egress fees.

Setup

1. Select Cloudflare R2 as the source type
2. Enter your Bucket name
3. Enter your Cloudflare Account ID (found in Cloudflare dashboard under R2 > Overview)
4. Add your R2 Access Key and Secret (create under R2 > Manage R2 API Tokens)

Google Cloud Storage

Connect using a GCP service account with storage.objects.get permission.

Setup

1. Select Google Cloud Storage as the source type
2. Enter your Bucket name and optional Project ID
3. Paste your Service Account JSON key (the full JSON from your GCP key file)

Azure Blob Storage

Connect using your Azure storage account credentials.

Setup

1. Select Azure Blob as the source type
2. Enter your Account Name and Container name
3. Add your Account Key (found in Azure Portal > Storage Account > Access Keys)
4. Optionally set a Prefix for blob name scoping

DigitalOcean Spaces

Spaces is S3-compatible. The endpoint is auto-configured from your region.

Setup

1. Select DigitalOcean Spaces as the source type
2. Enter your Bucket (Space name) and Region (e.g. nyc3, sfo3, ams3)
3. Add your Spaces Access Key and Secret (from DigitalOcean API panel)

Wasabi

Wasabi offers S3-compatible hot storage. The endpoint is auto-configured from your region.

Setup

1. Select Wasabi as the source type
2. Enter your Bucket name and Region (e.g. us-east-1, eu-central-1)
3. Add your Wasabi Access Key and Secret

Backblaze B2

B2 provides low-cost S3-compatible storage. The endpoint is auto-configured from your region.

Setup

1. Select Backblaze B2 as the source type
2. Enter your Bucket name and Region (find it in B2 dashboard under Buckets > Bucket Details, e.g. us-west-004)
3. Add your B2 Application Key ID and Application Key

Akamai / Linode Object Storage

Linode Object Storage is S3-compatible. The endpoint is auto-configured from your region.

Setup

1. Select Akamai / Linode as the source type
2. Enter your Bucket name and Region (e.g. us-east-1, eu-central-1)
3. Add your Linode Access Key and Secret Key

Web Proxy (HTTP)

Proxy and transform images from any public HTTP(S) URL. Great for existing CDNs or image servers.

Setup

1. Select Web Proxy (HTTP) as the source type
2. Enter the Base URL (e.g. https://cdn.example.com/images)

Image Foundry fetches originals from baseUrl + /path/to/image.jpg, applies transformations, and caches the result.

Image URLs

Image Foundry transforms images on-the-fly via URL. The format depends on which mode you chose when creating your source.

/my-source/cover/300x300/photo.jpg                      # Smart crop to 300x300
/my-source/width/800/format:auto,quality:75/photo.jpg    # Resize + auto format
/my-source/height/600/grayscale:true/photo.jpg           # Resize + grayscale
/my-source/cdn/photo.jpg                                 # No resize, optimize only
/my-source/cover/400x300/fp-x:0.3,fp-y:0.7/portrait.jpg # Focal point crop

/photo.jpg?w=800&h=600&fit=crop&auto=format              # Crop + auto format
/photo.jpg?w=400&blur=50&mono=44768B                     # Blur + grayscale tint
/photo.jpg?w=800&sharp=30&q=80                           # Sharpen + quality
/photo.jpg?w=600&h=400&fit=crop&fp-x=0.3&fp-y=0.7       # Focal point crop
/photo.jpg?w=500&dpr=2&auto=format,compress              # Retina + optimize

Custom Domains

Serve images from your own domain with full SSL:

1. Go to your project in the dashboard and click Add Domain
2. Enter your domain (e.g. img.yourdomain.com) and select the source to attach it to
3. Set a CNAME record with your DNS provider: img.yourdomain.com → proxy.
4. Click Verify in the dashboard once DNS has propagated
5. Start using it: https://img.yourdomain.com/width/800/photo.jpg

Resize Operations

Crop & Focal Point

Format & Quality

Filters & Effects

Overlays & Text

Watermark Overlay

# ImageBoss:
/width/700/wmk-path:%2Flogo.png,wmk-position:southeast,wmk-opacity:80/photo.jpg

# Imgix-style:
/photo.jpg?w=700&wmk-path=%2Flogo.png&wmk-position=southeast&wmk-opacity=80

Text Overlay

# ImageBoss:
/width/700/txt:Hello%20World,txt-size:60,txt-color:ffffff,txt-position:south/photo.jpg

Auto Optimizations

Automatic optimizations that require no manual configuration:

• Auto Orientation: EXIF rotation is always applied automatically
• Auto Format: Use format:auto or auto=format to serve the best format
• Progressive JPEG: Large JPEGs are automatically served as progressive
• Metadata Stripping: EXIF data is removed by default to reduce file size

Cache Purge

Image Foundry caches transformed images for fast delivery. When you update an original image, you can purge the cache to serve the new version immediately.

From the Dashboard

1. Open your project and go to the source
2. Click Purge Cache
3. Choose to purge a specific image path, a prefix, or everything

What Gets Purged

Purging an image path removes all variants of that image — every size, format, and quality combination. For example, purging /photos/hero.jpg clears the 400px webp version, the 800px avif version, and every other cached variant.

Usage & Analytics

Track your image delivery performance from the dashboard. Each project shows real-time usage metrics:

Usage is shown per source and per day, so you can spot trends and identify which sources drive the most traffic.

Signed URLs

Prevent unauthorized image transformations with HMAC SHA-256 signed URLs. Set a signing secret per source in the dashboard under source settings.

const crypto = require('crypto');

function signUrl(secret, path) {
  return crypto
    .createHmac('sha256', secret)
    .update(path)
    .digest('hex');
}

// ImageBoss style:
const path = '/width/400/photo.jpg';
const sig = signUrl('your-signing-secret', path);
const url = \`https://my-source.\${path}?s=\${sig}\`;

// Imgix style:
const imgixPath = '/photo.jpg?w=400';
const sig2 = signUrl('your-signing-secret', imgixPath);
const url2 = \`https://my-source.\${imgixPath}&s=\${sig2}\`;

CDN & Caching

Image Foundry is designed to sit behind Cloudflare or any CDN. All image responses include cache-friendly headers:

Cache-Control: public, max-age=2592000, s-maxage=2592000
CDN-Cache-Control: max-age=2592000
ETag: "sha256hash"
Vary: Accept

The Vary: Accept header ensures CDNs cache different formats (WebP, AVIF, JPEG) separately when auto-format is enabled.

304 Not Modified

Image Foundry supports conditional requests. Clients sending If-None-Match with a cached ETag receive 304 Not Modified with zero body, saving bandwidth.

Rate Limiting

Image delivery has no rate limit — images are served from cache and designed for high-traffic production use. Dashboard and account actions are rate-limited to prevent abuse (10 requests/minute for login, 100 requests/minute for other actions).

Migration Guide

Migrating from Imgix

1. Add a source and choose Imgix as the URL style
2. Point it to the same S3/GCS/Azure bucket that Imgix is using
3. Update your DNS or image URLs:
   my-site.imgix.net → my-source.
4. All Imgix query parameters (?w=, ?h=, ?fit=, ?auto=, etc.) work as-is

Migrating from ImageBoss

1. Add a source and choose ImageBoss as the URL style
2. Connect it to your storage provider
3. Replace img.imageboss.me/your-source/ with img./your-source/
4. All ImageBoss path-based URLs work as-is

Migrating from Cloudinary

1. Export your images to S3, GCS, or any supported storage
2. Add a source in Image Foundry pointing to your storage
3. Map Cloudinary transformations to ImageBoss/Imgix equivalents
4. Common mappings: c_fill → fit=crop, c_fit → fit=clip, w_400 → w=400, f_auto → auto=format

Error Codes

Error responses return JSON:

{
  "error": "NOT_FOUND",
  "message": "Image not found in source: photos/nonexistent.jpg"
}