Zimage Usage

A fast image processor for any app that serves remote images.

Introduction

Zimage was created because many image processors are not fast enough to meet the demands of today’s apps, especially on mobile. While it’s not yet perfect, it’s based on a solid starting point and the current results are promising.

This project started out of a few straightforward requirements:

  1. Free. It should be free to use
  2. Simple. It’s API should be extremely simple and flexible
  3. Pull-based. It must be a “pull” model where it fetches source images from origin servers, wherever they are
  4. Caching. It must automatically handle end-to-end caching at the edges and at its servers
  5. Optimizing. It should automatically generate the most lossless, optimal images based on user parameters
  6. Analytics. It should allow for more aggressive caching and provide detailed dashboards and insights to paying customers

Using Zimage

Zimage is free to use and suitable for most basic applications. However, if you intend to serve large amounts of content from many source images, you will want to look at our pricing plan for paid customers.

Zimage serves and transforms images via its simple REST API. The best way to demonstrate the API is by example.

Note: This documentation details the “Free” version of Zimage, so everything here is available for you to use unless otherwise stated.

Javascript API

The easiest way to start using Zimage for free is to use the Zimage Javascript library directly. While currently extremely simple, there is active development to add features such as “blur up” on images.

Without further ado:

import React, { Component } from 'react';
import zimage from 'zimage';

class Avatar extends Component {
  render() {
    const imageUrl = zimage(this.props.imageUrl, { width: 32 });
    return <img src={imageUrl} />;
  }
}

This extremely simplified example renders an avatar image (thumbnail) by resizing it to the desired width of 32px. Zimage will automatically fetch, resize, and cache the image for immediate use. Furthermore, if your site is served over HTTPS, it will use HTTPS, otherwise HTTP.

Here is a full list of available properties for free:

  • width: Desired width for image. If no height is specified, the aspect ratio will be preserved
  • height: Desired height for image. If no width is specified, the aspect ratio will be preserved
  • flip={x | y | xy} Flips the image horizontally, vertically, or both
  • format={jpeg | png | webp | gif}: Transforms the source image into the given format
  • mode={pad | crop | portrait | landscape | stretch}: Declares the strategy to use when resizing the image. Defaults to pad
  • anchor={center | top | right | left | bottom}: Desired edge to base the crop on. Defaults to center
  • interp={bicubic | bilinear | nohalo}: Desired interpolation algorithm when resizing the image. Defaults to bicubic
  • quality: Desired quality for jpeg images. Defaults to 80
  • blur: Gamma (sigma) value for blurring an image.

REST api

The most flexible way to get started is to simply request your image via HTTP or HTTPS through Zimage with the desired parameters. Zimage can fetch images via HTTP or HTTPS (the former will be faster in the cold cache case), but it’s up to you. It’s recommended to use Zimage’s HTTPS endpoint.

There are two domains that use Zimage’s edge cache for the free tier:

  • HTTP: http://edge.zimage.io
  • HTTPS: https://zimage.global.ssl.fastly.net/

This is important when embedding URLs directly (e.g., for mobile apps or CSS declarations). All of the aforementioned properites above are available via teh REST API.

For example:

# Resize the given image to a max width of 288 and blur it.

http://edge.zimage.io/?url=https://s3-us-west-2.amazonaws.com/stllc/zimage/images/ferrari.png&blur=5&w=288