# h2non/imaginary

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/h2non-imaginary).**

6,017 stars · 492 forks · Go · mit

## Links

- GitHub: https://github.com/h2non/imaginary
- Homepage: https://fly.io/docs/app-guides/run-a-global-image-service/
- awesome-repositories: https://awesome-repositories.com/repository/h2non-imaginary.md

## Topics

`crop-image` `docker` `gif` `image` `image-processing` `jpeg` `libvips` `microservice` `png` `resize-images` `watermark` `webp`

## Description

Imaginary is a self-hosted HTTP server for image processing that applies transformations like resizing, cropping, rotating, and format conversion through URL parameters. It operates as a stateless request-response pipeline, processing images fetched from remote URLs or served from a local directory without requiring client-side dependencies.

The server distinguishes itself through its security and access control capabilities, offering optional API key validation, HMAC-signed URL verification, and remote origin whitelisting to restrict which image sources are permitted. It also provides a health and metrics endpoint for monitoring server statistics, and supports chaining multiple operations in a single request by encoding transformations as sequential URL parameters.

Beyond core transformations, the service includes watermark overlay with text or remote images, smart cropping, blur effects, metadata extraction, and placeholder image serving on error. It supports CORS configuration for browser-based access and request concurrency throttling to manage server load.

## Tags

### Graphics & Multimedia

- [Image Processing](https://awesome-repositories.com/f/graphics-multimedia/image-editing-processing/image-processing.md) — Send image transformation commands through URL parameters to process images programmatically on the server. ([source](https://fly.io/docs/app-guides/run-a-global-image-service/))
- [Processing APIs](https://awesome-repositories.com/f/graphics-multimedia/image-editing-processing/image-processing/processing-apis.md) — Exposes image transformation operations like resize, crop, rotate, and watermark through a simple HTTP API.
- [Image Cropping Tools](https://awesome-repositories.com/f/graphics-multimedia/image-editing-processing/image-editors/image-cropping-tools.md) — Crops images to specified dimensions with optional gravity control. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [On-Demand Thumbnail Generation](https://awesome-repositories.com/f/graphics-multimedia/image-editing-processing/image-editors/image-cropping-tools/on-demand-thumbnail-generation.md) — Creates smaller versions of images suitable for previews or listings. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Dimension Resizing](https://awesome-repositories.com/f/graphics-multimedia/image-editing-processing/image-processing/dimension-resizing.md) — Scales images to new dimensions while preserving aspect ratio or applying exact sizes. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [HTTP-Driven Pipelines](https://awesome-repositories.com/f/graphics-multimedia/image-processing-pipelines/http-driven-pipelines.md) — Processes images by accepting HTTP requests with URL parameters that specify operations, chaining transformations through sequential middleware.
- [Format Converters](https://awesome-repositories.com/f/graphics-multimedia/media-processing-analysis/media-manipulation/media-processing-workflows/image-processing-pipelines/image-format-decoders/format-converters.md) — Converts images between formats like JPEG, PNG, and WebP with quality settings. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Image Metadata Extraction](https://awesome-repositories.com/f/graphics-multimedia/image-metadata-extraction.md) — Returns image dimensions, format, color space, and orientation as JSON. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Image Orientation Manipulators](https://awesome-repositories.com/f/graphics-multimedia/image-orientation-manipulators.md) — Mirrors images horizontally or vertically to reverse orientation. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Text Overlays](https://awesome-repositories.com/f/graphics-multimedia/text-overlays.md) — Overlays customizable text onto images with control over font, color, opacity, and position. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Thumbnail Services](https://awesome-repositories.com/f/graphics-multimedia/video-production/thumbnail-services.md) — Generates scaled-down image previews with configurable dimensions and aspect ratio preservation.

### Web Development

- [Server-Side Image Editing](https://awesome-repositories.com/f/web-development/server-side-image-editing.md) — Provides a self-hosted HTTP server for editing existing images via URL parameters.

### Data & Databases

- [Image Transformations](https://awesome-repositories.com/f/data-databases/file-storage-and-metadata-management/image-transformations.md) — Applies operations such as rotation, flipping, watermarking, or format conversion to an image. ([source](https://fly.io/launch/github/h2non/imaginary))
- [Image Transformation Proxies](https://awesome-repositories.com/f/data-databases/file-storage-and-metadata-management/image-transformations/image-transformation-proxies.md) — Ships a proxy that fetches remote images, applies operations, and returns results with CORS support.

### DevOps & Infrastructure

- [Image Processing Stage Chains](https://awesome-repositories.com/f/devops-infrastructure/dockerfile-utilities/dockerfile-inheritance/multi-stage-build-pipelines/image-processing-stage-chains.md) — Chains multiple image transformations in a single request, passing output to input. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Image Processing APIs](https://awesome-repositories.com/f/devops-infrastructure/infrastructure/private-enterprise-management/self-hosted-services/self-hosted-api-services/image-processing-apis.md) — Provides a deployable API for programmatic image manipulation with remote URL fetching.
- [Remote Image Fetchers](https://awesome-repositories.com/f/devops-infrastructure/remote-resource-fetching/remote-image-fetchers.md) — Fetches images from remote HTTP URLs for server-side processing. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Remote Image Fetching](https://awesome-repositories.com/f/devops-infrastructure/remote-resource-fetching/remote-image-fetching.md) — Fetches images from remote HTTP URLs for processing instead of requiring direct file uploads.

### Networking & Communication

- [Operation Chaining](https://awesome-repositories.com/f/networking-communication/communication-protocols-architectures/request-processing-architectures/request-processing/parameter-driven-middleware/operation-chaining.md) — Encodes a sequence of image transformations as URL query parameters, executing them in order within a single request.
- [Image Processing Servers](https://awesome-repositories.com/f/networking-communication/http-clients/http-servers/image-processing-servers.md) — An HTTP server that applies transformations like resize, crop, rotate, and format conversion to images via URL parameters.

### Security & Cryptography

- [Middleware](https://awesome-repositories.com/f/security-cryptography/security/policies/access-control/middleware.md) — Enforces access controls through optional API key validation, HMAC URL signing, and remote origin whitelisting as middleware layers.
- [API Key Authentication](https://awesome-repositories.com/f/security-cryptography/api-key-authentication.md) — Requires a token passed via header or query parameter to authorize each image processing request. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Secure Image Delivery](https://awesome-repositories.com/f/security-cryptography/code-signing/secure-image-delivery.md) — Protects image processing endpoints with API keys, signed URLs, origin validation, and CORS controls.
- [Origin Validators](https://awesome-repositories.com/f/security-cryptography/cross-origin-security-policies/origin-validators.md) — Restricts image processing to URLs from a specified list of allowed hostnames and paths. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [API Access Restrictions](https://awesome-repositories.com/f/security-cryptography/domain-access-restrictions/request-access-restrictions/api-access-restrictions.md) — Enforces token-based authorization via API key passed in headers or query parameters. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [URL Signature Validation](https://awesome-repositories.com/f/security-cryptography/url-signature-validation.md) — Validates requests by requiring an HMAC-SHA256 signature computed from the URL path and query parameters. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))

### Artificial Intelligence & ML

- [Smart Cropping](https://awesome-repositories.com/f/artificial-intelligence-ml/computer-vision-systems/computer-vision/facial-analysis-systems/face-detection/smart-cropping.md) — Automatically detects and crops the most interesting region of an image. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))

### Part of an Awesome List

- [Rectangular Region Extraction](https://awesome-repositories.com/f/awesome-lists/media/pixel-level-image-manipulation/regional-image-processing/rectangular-region-extraction.md) — Extracts a rectangular region from an image based on coordinates and dimensions. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Image Processing](https://awesome-repositories.com/f/awesome-lists/media/image-processing.md) — Provides an HTTP microservice for image resizing.

### Software Engineering & Architecture

- [Stateless Architectures](https://awesome-repositories.com/f/software-engineering-architecture/stateless-architectures.md) — Handles each image processing request independently without session state, enabling horizontal scaling and simple deployment.

### System Administration & Monitoring

- [Health Monitoring Endpoints](https://awesome-repositories.com/f/system-administration-monitoring/monitoring-and-observability/observability-platforms/operational-health-alerting/health-monitoring-endpoints.md) — Exposes server statistics and application health data via a JSON endpoint for monitoring and observability.

### User Interface & Experience

- [Gaussian Blur Implementations](https://awesome-repositories.com/f/user-interface-experience/animation-and-motion-systems/blur-effects/gaussian-blur-implementations.md) — Applies Gaussian blur to images with a configurable sigma value. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Image Watermark Overlays](https://awesome-repositories.com/f/user-interface-experience/content-rendering-components/image-overlays/media-watermarking-tools/image-watermark-overlays.md) — Overlays remote images as watermarks onto other images with adjustable opacity. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Visible Watermark Overlays](https://awesome-repositories.com/f/user-interface-experience/content-rendering-components/image-overlays/media-watermarking-tools/visible-watermark-overlays.md) — Adds visible text or image watermarks with configurable opacity and positioning. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Watermark Overlay Tools](https://awesome-repositories.com/f/user-interface-experience/content-rendering-components/image-overlays/media-watermarking-tools/watermark-overlay-tools.md) — Overlays text or remote image watermarks with adjustable opacity and positioning via API.
- [Remote URL](https://awesome-repositories.com/f/user-interface-experience/data-display-components/content-cards/image-resizing/remote-url.md) — Accepts a URL to a remote image and resizes it to specified dimensions. ([source](https://fly.io/docs/app-guides/run-a-global-image-service/))
- [Error Placeholders](https://awesome-repositories.com/f/user-interface-experience/image-placeholders/error-placeholders.md) — Ships a configurable fallback image when processing fails, preventing broken-image errors. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Aspect Ratio Preserving Resizing](https://awesome-repositories.com/f/user-interface-experience/resizable-panes/dimension-controllers/minimum-dimension-calculators/image-bounding-boxes/aspect-ratio-preserving-resizing.md) — Resizes images to fit within a bounding box while preserving aspect ratio. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))
- [Remote Source Validators](https://awesome-repositories.com/f/user-interface-experience/ui-components/image-view-components/image-thumbnails/remote-image-loaders/remote-source-validators.md) — Limits which remote URLs the service can fetch images from by validating host and path patterns. ([source](https://cdn.jsdelivr.net/gh/h2non/imaginary@master/README.md))