hendridm/image-mason repository overview

⁠Image Mason

A self-hosted HTTP API that makes JPEG, PNG, WebP, AVIF and JPEG XL images smaller, converts between those formats, and can host the results temporarily. A web UI is included (shown above) for testing and convenience.

Compression settings are usually a guess: a setting that suits one photo blurs a diagram or wastes bytes on another. Image Mason measures instead. Each lossy result is scored against the original with SSIMULACRA2⁠, a perceptual quality metric, and the service returns the smallest file that meets the preset's minimum score, searching across several encoders and their settings.

• JPEG: lossless recompression with jpegtran (mozjpeg), and lossy encoding with Google's jpegli⁠.
• PNG: lossless recompression with oxipng, and palette quantization with pngquant.
• WebP: lossy and lossless encoding with cwebp (libwebp).
• AVIF: lossy and lossless encoding with avifenc (libavif, with the aom AV1 encoder).
• JPEG XL: lossy and lossless encoding with cjxl (libjxl), and lossless recompression of JPEGs.
• Conversion: any of the five formats to any other, with the same quality presets.
• Resizing: fit into a box, fill it and crop (centered or on the most interesting area), or stretch, with libvips.
• Cropping: keep an exact area, then resize or convert it in the same call.
• Hosting: results can be stored and served from a URL for a limited time.
• Web interface: open an image in the browser, try the options, compare the result with the original and download it.

The image is about 70 MB (30 MB to download), is published for linux/amd64 and linux/arm64, and runs as a non-root user. It works with a read-only root filesystem: only /data (stored images) and /tmp (scratch files) need to be writable, as in the Compose file⁠.

⁠Contents

• Quick Start⁠
• Usage⁠
• Endpoints⁠
• Configuration⁠
• Memory⁠
• Security⁠
• Development⁠
• License⁠

⁠Quick Start

docker run -d --name image-mason -p 8080:8080 \
  -e IMAGE_MASON_API_KEY=change-me \
  -v image-mason-data:/data \
  --memory 4g \
  hendridm/image-mason

Open http://localhost:8080⁠ to use the web interface (it asks for the key), or http://localhost:8080/docs⁠ for usage examples. Or optimize an image from the command line:

curl -sS -H "X-Api-Key: change-me" --data-binary @photo.jpg -o photo.min.jpg \
  http://localhost:8080/api/v1/transform

⁠Docker Compose

Download docker-compose.yml⁠ and .env.sample⁠, then:

cp .env.sample .env    # set IMAGE_MASON_API_KEY
docker compose up -d

The sample Compose file runs the container read-only with a 4 GB memory limit and a named volume for stored images.

⁠Tags

⁠Usage

Every job goes to one endpoint, POST /api/v1/transform. On its own it optimizes the image: the same format and size, as small as the quality preset allows. Parameters add steps: crop to keep an area, width and height to resize, and format to convert. The result is always optimized.

⁠Optimize an Image

Send the image as the raw request body:

curl -sS -H "X-Api-Key: change-me" --data-binary @photo.jpg -o photo.min.jpg \
  "http://localhost:8080/api/v1/transform?quality=medium"

Or pass a URL for the service to download:

curl -sS -X POST -H "X-Api-Key: change-me" -o photo.min.jpg \
  "http://localhost:8080/api/v1/transform?url=https://example.com/photo.jpg"

The response body is the optimized image. Its statistics are in the response headers:

X-Image-Mason-Quality: high
X-Image-Mason-Original-Size: 93694
X-Image-Mason-Size: 47521
X-Image-Mason-Size-Change-Percent: -49.28
X-Image-Mason-Original-Dimensions: 640x427
X-Image-Mason-Dimensions: 640x427
X-Image-Mason-Method: jpegli-d1.15
X-Image-Mason-Score: 86.19
X-Image-Mason-Min-Score: 85
X-Image-Mason-Duration-Ms: 209

⁠Convert an Image

Add format: jpeg, png, webp, avif or jxl.

curl -sS -H "X-Api-Key: change-me" --data-binary @photo.jpg -o photo.webp \
  "http://localhost:8080/api/v1/transform?format=webp"

The result is optimized the same way: the smallest encoding that meets the quality preset. format=auto turns a PNG that's really a photo into a JPEG and leaves other images in their format.

⁠Resize an Image

Add width, height or both. On its own, width sets the width and the height follows. Add upscale=false to only shrink:

# 1200 wide
curl -sS -H "X-Api-Key: change-me" --data-binary @photo.jpg -o photo-1200.jpg \
  "http://localhost:8080/api/v1/transform?width=1200"

# At most 1200 wide: smaller images are left as they are
curl -sS -H "X-Api-Key: change-me" --data-binary @photo.jpg -o photo-max-1200.jpg \
  "http://localhost:8080/api/v1/transform?width=1200&upscale=false"

# Fit inside 1200x800, keeping the aspect ratio
curl -sS -H "X-Api-Key: change-me" --data-binary @photo.jpg -o photo-1200x800.jpg \
  "http://localhost:8080/api/v1/transform?width=1200&height=800&fit=contain"

# A 400x400 square thumbnail as WebP, cropped to the most interesting area
curl -sS -H "X-Api-Key: change-me" --data-binary @photo.jpg -o thumb.webp \
  "http://localhost:8080/api/v1/transform?width=400&height=400&fit=cover&position=attention&format=webp"

⁠Crop an Image

Add crop, the area to keep as left,top,width,height in pixels. width and height then resize the cropped area, and format converts it:

# The 480x480 square starting 80 pixels from the left
curl -sS -H "X-Api-Key: change-me" --data-binary @photo.jpg -o square.jpg \
  "http://localhost:8080/api/v1/transform?crop=80,0,480,480"

# The same square as a 200x200 AVIF
curl -sS -H "X-Api-Key: change-me" --data-binary @photo.jpg -o square.avif \
  "http://localhost:8080/api/v1/transform?crop=80,0,480,480&width=200&format=avif"

⁠Quality Presets

Scores are SSIMULACRA2, from 0 to 100, where 100 is identical. Use minScore for a custom floor, or change the default preset and the preset floors with environment variables⁠.

⁠Store and Share an Image

Add store=true to store the result and get its URL instead of the bytes:

curl -sS -H "X-Api-Key: change-me" --data-binary @graphic.png \
  "http://localhost:8080/api/v1/transform?store=true"

{
  "output": "http://localhost:8080/images/f100579fc856433e9a5b56c49ee9e420.png",
  "mimeType": "image/png",
  "originalSize": 9810,
  "size": 894,
  "sizeChangePercent": -90.89,
  "originalWidth": 480,
  "originalHeight": 320,
  "width": 480,
  "height": 320,
  "quality": "medium",
  "method": "pngquant+oxipng",
  "score": 90.31,
  "minScore": 80,
  "isPhoto": false,
  "expiresAt": "2026-10-24T16:32:24-04:00",
  "durationMs": 668
}

Stored images are served at /images/{name} until expiresAt (60 minutes by default), then deleted. To store an image without changing it, use POST /api/v1/upload⁠.

⁠Errors

Errors are returned as RFC 9457 Problem Details⁠ with the application/problem+json content type:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.16",
  "title": "Unsupported Media Type",
  "status": 415,
  "detail": "Unsupported image format; expected JPEG, PNG, WebP, AVIF or JPEG XL.",
  "traceId": "00-2505c8a26cb460e47d2be04e45c74d8c-9d260fe1868f535e-00"
}

⁠Endpoints

When IMAGE_MASON_API_KEY is set, the /api endpoints require it in the X-Api-Key header, except GET /api/v1/limits.

⁠POST /api/v1/transform

Optimizes the image, after cropping, resizing and converting it when asked. The image is the request body, the file at url, or a stored image named by source. Parameters it doesn't take get 400, naming them.

Response headers:

⁠How Each Format Is Handled

Lossy encoders search their quality setting for the smallest result that meets the floor, scoring each attempt against the input. Scores come from ssim2, built on fast-ssim2⁠: it reads images and their color profiles the way libjxl's ssimulacra2 does and matches its scores to within 0.07 (0.25 on images with transparency). For an opaque image it prepares the input once per job instead of once per attempt.

• JPEG: jpegtran recompresses a JPEG without loss, keeping the ICC color profile (and the EXIF data, when the image relies on its orientation tag). Unless the preset is lossless, jpegli encodes it too. JPEG has no lossless mode, so a JPEG produced by cropping, resizing or converting under lossless is held to a score of 90 instead. Transparent images are placed on white.
• PNG: oxipng recompresses without loss. Unless the preset is lossless, pngquant reduces the palette, and the result is kept only if it meets the floor.
• WebP: cwebp encodes lossy, and also lossless when the input is a PNG graphic or the preset is lossless. Lossy WebP can't reach every floor on detailed photos; lossless is then the fallback.
• AVIF: avifenc encodes lossy, or lossless under the lossless preset.
• JPEG XL: cjxl encodes lossy, and also lossless when the input is a PNG graphic or the preset is lossless. A JPEG at its original size is also recompressed without loss (cjxl-jpeg), typically 20% smaller.
• Orientation: every re-encoded result is rotated upright, so it displays correctly without an orientation tag. Metadata other than the ICC color profile is removed.
• Cropped and resized images start from the cut-out or downscaled pixels, and are scored against them.

When the output format matches the input, the original is always a candidate, so the response is never larger than the input unless a crop or resize asked for a different image. Animated WebP, AVIF and JPEG XL are rejected.

⁠Cropping, Resizing and Converting

• Cropping: the area is in display pixels, so for a photo with an orientation tag it matches what a viewer shows, not the stored pixels. A crop that reaches past the image's edges gets 400, with the image's displayed size in the message. X-Image-Mason-Original-Dimensions still reports the whole input.
• Scores: a cropped or resized result is optimized against the cropped or resized pixels, so its score compares it with those, not with the original.
• Size limits: results over IMAGE_MASON_MAX_PIXELS, and WebP results over 16383 pixels on a side, get 422.
• Bit depth: converting to JPEG or WebP reduces 16-bit images to 8 bits per channel.

⁠POST /api/v1/upload

Stores a JPEG, PNG, WebP, AVIF or JPEG XL unchanged, animated ones included, and returns the same JSON as transform?store=true. It doesn't wait for a job slot. Accepts the image as the body or url, and filename. The name in output can then be passed as source to transform and info.

⁠POST /api/v1/info

Reads the image's headers without decoding it, so it's fast and doesn't wait for a job slot. Accepts the image as the body, url or source.

curl -sS -H "X-Api-Key: change-me" --data-binary @photo.jpg http://localhost:8080/api/v1/info

{
  "format": "jpeg",
  "mimeType": "image/jpeg",
  "size": 93794,
  "width": 640,
  "height": 427,
  "orientation": 6,
  "displayWidth": 427,
  "displayHeight": 640,
  "megapixels": 0.27,
  "bitDepth": 8,
  "hasAlpha": false,
  "hasIccProfile": false,
  "animated": false,
  "withinPixelLimit": true
}

orientation is the EXIF orientation (1 is upright), and displayWidth and displayHeight apply it. hasAlpha means the image has an alpha channel, even if every pixel is opaque. PNGs within the pixel limit also report isPhoto. withinPixelLimit says whether transform accepts the image under IMAGE_MASON_MAX_PIXELS.

When a JPEG, PNG or WebP carries EXIF, exif summarizes it. Fields the image doesn't have are left out:

"exif": {
  "make": "Canon",
  "model": "Canon EOS R5",
  "lensModel": "RF24-70mm F2.8 L IS USM",
  "software": "Lightroom 13",
  "dateTaken": "2026-05-01T14:30:00+02:00",
  "artist": "Jane Doe",
  "copyright": "(c) 2026 Jane Doe",
  "iso": 800,
  "fNumber": 4,
  "exposureTime": "1/125",
  "focalLength": 35,
  "gps": { "latitude": 48.85837, "longitude": 2.294481, "altitude": 35 }
}

gps is where the photo was taken.

⁠GET /api/v1/limits

What this server accepts, so a client can check an image before sending it. The values come from the configuration⁠. It needs no API key, so a client can read apiKeyRequired before asking for one.

{
  "formats": [
    { "name": "png", "mimeType": "image/png", "extension": ".png", "bytesPerPixel": 48 },
    { "name": "webp", "mimeType": "image/webp", "extension": ".webp", "maxSide": 16383, "bytesPerPixel": 32 },
    { "name": "jpeg", "mimeType": "image/jpeg", "extension": ".jpg", "maxSide": 65535, "bytesPerPixel": 16 },
    { "name": "jxl", "mimeType": "image/jxl", "extension": ".jxl", "bytesPerPixel": 32 },
    { "name": "avif", "mimeType": "image/avif", "extension": ".avif", "bytesPerPixel": 40 }
  ],
  "maxInputSize": 26214400,
  "maxPixels": 50000000,
  "presets": { "lossless": null, "high": 85, "medium": 80, "low": 70 },
  "defaultQuality": "high",
  "imageTtlMinutes": 60,
  "timeoutSeconds": 120,
  "urlFetch": true,
  "apiKeyRequired": true,
  "jobMemory": { "budget": 4026531840, "overhead": 67108864, "scoringBytesPerPixel": 150 }
}

maxSide is the largest width or height a format can store; without it, only maxPixels applies. presets gives each preset's minimum score.

jobMemory tells a client whether the server has the memory for a job before it sends the image (see Memory⁠). A job needs overhead, plus the larger of the input's and the result's pixel counts times the larger of the two formats' bytesPerPixel, plus the result's pixels times scoringBytesPerPixel when it's held to a score (every preset but lossless, and lossless to JPEG when the image is cropped, resized or converted). A job that needs more than budget gets 422.

⁠GET /images/{name}

Serves a stored image until it expires. These URLs need no API key: anyone who has one can fetch the image.

⁠DELETE /images/{name}

Deletes a stored image before it expires. Unlike fetching, this needs the API key. Returns 204, or 404 when there's no image by that name (including one that already expired). An image stored with keepOriginal has two names, output and input; delete each separately.

curl -sS -X DELETE -H "X-Api-Key: change-me" http://localhost:8080/images/banner.webp

⁠GET /health

Returns the service status, uptime and build information (version, build date, .NET runtime and architecture). The image's HEALTHCHECK uses this endpoint.

⁠Configuration

All settings are environment variables, and all are optional. Sizes are in bytes or use a suffix: 25m, 10g. .env.sample⁠ lists them with comments. An invalid value stops the container at startup with a message naming the variable.

Stored images are kept in /data/images. Mount a volume at /data to keep them across container restarts; they still expire after IMAGE_MASON_IMAGE_TTL_MINUTES.

⁠Memory

Scoring a lossy result takes far more memory than encoding it: about 150 MB per megapixel. A 12 MP phone photo needs about 2 GB at high, medium or low, whatever the output format. Lossless jobs need much less: up to about 16 MB per megapixel for JPEG, 32 MB for WebP and JPEG XL, 40 MB for AVIF and 48 MB for PNG.

Time grows with size the same way. With 4 CPUs, a 15 MP photo at high takes about 10 seconds as JPEG and 10 to 20 seconds as AVIF or WebP, which need more encoding attempts. Raise IMAGE_MASON_TIMEOUT_SECONDS if you send large images with a short timeout.

The service guards against running out of memory:

• Each job reserves its estimated peak memory before it starts. Jobs wait in order while memory is in use.
• A job that could never fit gets 422 instead of waiting.
• The budget is the container's memory limit minus 256 MB for the service itself. Set IMAGE_MASON_MEMORY_LIMIT when there is no container limit, or to share the host with other services.
• If the kernel still kills an image tool, the request gets 503 with Retry-After, and the service keeps running.

Set a container memory limit (--memory or the Compose memory limit) that fits your largest images, and send width when you don't need full-resolution output: memory for scoring depends on the output size.

⁠Security

Image Mason is built for private networks and trusted callers.

• Set an API key unless only trusted clients can reach the port. Without one, anyone who can reach the service can use it, and the container logs a warning at startup.
• Use TLS. The service speaks plain HTTP. Put it behind a reverse proxy for HTTPS, and set `IMAGE_MASON_PUBLIC_BASE_URL