How it works

  1. You link images through snappyimg, specifying desired resolution, resize mode, etc.
  2. The first time someone loads the asset, snappyimg downloads your original image and processes it.
  3. All further requests for the image are served from cache.

Implementation details

Instead of linking your image directly such as <img src="$imageUrl">, you use a signed URL that looks roughly like this:
https://serve.snappyimg/…/$imageUrl. You may assemble the URL on your servers manually, but there are multiple implementations available what will greatly simplify the process.

Ⓐ Building the URL with a library

Each library is documented in its repository.

Ⓑ Building the URL manually

The full url format for snappyimg is this:
https://$stage.snappyimg.com/$appToken/$signature/$options/base64($imageUrl).$format
Signed portion of the url
$stage Either demo or serve. Demo is available is Free plan, but places a watemark on all images. Should only be used for development and testing. Production value is serve and is only available in Paid subscription.
$appToken Value we generate for you when you register.
$signature

The signature is a base64 encoded output of a SHA256 HMAC. It prevents 3rd parties from using your paid account maliciously.

You compute this value based on the remaining parameters. The formula is:
$toSign := /$options/base64($imageUrl).$format
$signature := base64(hmac(algo: SHA256, key: $appSecret, data: $toSign))

Where $appSecret is another value we generate for you when you register.

$options Configuration for the final image in the following format: $resize/$width/$height/$gravity/$enlarge Allowed values are explained below.
$resize Allowed values are
  • fit Keep aspect ratio and resize. Resulting image will be exact on $width or $height and smaller on the other. If given $width×$height is in same aspect ratio as the original image, both dimensions will be exact. In that case the behaviour is identical to fill.
  • fill Keep aspect ratio and fill to given dimensions, cropping overflow.
  • crop Crop to given $width×$height without resizing.
$width,
$height
Maximum dimensions in pixels the resulting image should have. Based on the combinations of $resize and $enlarge, the actual dimensions may be smaller.
$gravity Tells snappyimg how to position an image in canvas when a part of the image (if any) should be cropped. Allowed values are sm detect interesting areas automatically, ce center, no top edge, so bottom edge, ea right edge and we left edge.
$enlarge Whether original image should be scaled-up to given $width×$height if it is smaller. Value of 1 allows scaling-up, 0 disables it.
$format One of png, jpg or webp. If the original image is in different format, it is converted. Transparency is supported.

Guarantees

Our processing servers have an overall uptime of 99.950%. Furthermore, once an image is processed, all requests are handled exclusively by Cloudflare edge servers.

On the first request most images are processed in under 800 milliseconds. Subsequent requests are served from cache in under 50 milliseconds.

Limitations

  • Maximum width and height: 16384 pixels
  • Maximum resolution: 50 megapixels