1. Products
  2.   Image
  3.   GO
  4.   imaginary

Go API for HTTP Based Image Processing

Open Source Go Library that supports Online smart cropping, flip or rotate images, create image thumbnails, image zooming, adding watermark to PNG, WEBP, TIFF, PDF, GIF, and SVG, etc.

The imaginary is a very powerful open source HTTP based image processing Go API that gives software developers the power to perform advanced image operations via private or public HTTP services with lesser dependency. It supports advanced operations like API token authorization, URL signature protection, HTTP traffic throttle strategy, and CORS support for web clients. The library can read images from HTTP POST payloads, server local paths, or remote HTTP servers.

The imaginary is a powerful and stable library built on top of libvips a fast and efficient image processing. The library has included support for image formats such as JPEG, PNG, HEIF, WEBP, TIFF, PDF, GIF, and SVG formats as well as transparent conversion across them. It has provided complete support for Docker & Fly.io. The great thing about Fly is that it can lessen latency and provide better practice by serving traffic close to your user’s location.

The imaginary library fully supports several important features related to image creation, conversion, and manipulation such as image resizing, enlarging images, image cropping, smart-crop, rotating images, AutoRotate with further image transformations, auto-flip based on EXIF metadata, image flop, zoom images, create images thumbnails, fit images, embed or extend an image, add watermark image, add blur effects to an image and many more.

Previous Next

Getting Started with imaginary

The easiest and recommended way to install imaginary is via GitHub.

Install imaginary via GitHub

go get -u github.com/h2non/imaginary

Convert Images to Other Formats via Go

The open-source API imaginary library has included support for converting your images to other supported file formats with ease. You can save images in some very useful formats like JPEG, PNG, and WEBP formats. The library has provided conversion support with additional quality and compression settings. You just need to provide the correct image name, address & conversion format and the library will easily convert it for you with just a couple of Go commands.

Convert Image via Imaginary Library

func Convert(buf []byte, o ImageOptions) (Image, error) {
	if o.Type == "" {
		return Image{}, NewError("Missing required param: type", http.StatusBadRequest)
	if ImageType(o.Type) == bimg.UNKNOWN {
		return Image{}, NewError("Invalid image type: "+o.Type, http.StatusBadRequest)
	opts := BimgOptions(o)

	return Process(buf, opts)

Online Image Cropping via Go

The open source imaginary library enables software developers to crop their images online with just a couple of lines of Go code inside their own applications. You can crop your image by providing custom width or height. The library makes your job easy by maintaining the Image ratio. The library also supports cropping the image by using the libvips built-in smart crop algorithm. You can also define the image compression level for PNG images and flip, flop, and rotate your images with ease.

Image Cropping via Go Library

    "operation": "crop",
    "params": {
      "width": 500,
      "height": 300

Resize Images to Fit

The Free imaginary library has included support for resizing images to fit using Go commands inside their apps.  You can easily resize an image to fit within width and height, without cropping. The library makes your job easy by maintaining the image aspect ratio. The width and height specify a maximum bounding box for the image.

Resize Image via Free Go Library

func Resize(buf []byte, o ImageOptions) (Image, error) {
	if o.Width == 0 && o.Height == 0 {
		return Image{}, NewError("Missing required param: height or width", http.StatusBadRequest)

	opts := BimgOptions(o)
	opts.Embed = true

	if o.IsDefinedField.NoCrop {
		opts.Crop = !o.NoCrop

	return Process(buf, opts)

Rotate and Auto-Rotate Your Images

The Free imaginary library has provided functionality for rotating your images with ease. It has also included a very useful function for auto-rotating images inside Go applications. It automatically rotates the image with no further image transformations based on EXIF orientation metadata. The AutoRotate method produces a new image with the same size and format as the input image.

Auto-Rotate Image via Free Go Library

func AutoRotate(buf []byte, o ImageOptions) (out Image, err error) {
	defer func() {
		if r := recover(); r != nil {
			switch value := r.(type) {
			case error:
				err = value
			case string:
				err = errors.New(value)
				err = errors.New("libvips internal error")
			out = Image{}