Getting Started

LibPixel is a realtime image manipulation service for any images that are available on the internet.

To get started, all you need is a LibPixel account: you can sign up for free here.

How it works

LibPixel works by fetching images from an existing Image Source, processing them on the fly and responding with the modified image.

You simply supply the image size or processing you want in the query string in the URL you use for the image (perhaps in an IMG tag), and LibPixel does the rest.

<img src="https://yourdomain.libpx.com/my-images/avatar.jpg?width=210">

LibPixel is designed to be fast. It is likely that the transit/download time will be far more significant than the time taken by LibPixel to process the image, so in practice processed images are delivered as fast or faster (due to caching and CDN) than the original image.

How it works

You never have to upload your images to LibPixel, so you retain full control over storage. And you only need to store the original images, not any modified versions.

Supported images

The image formats supported by LibPixel are JPEG, PNG, GIF and WebP. The output image type will be the same as the input type.

By default we limit source images to a maximum of 16 megapixels and 16 megabytes. If you need higher limits, please contact us.

Image Sources

LibPixel supports two modes of fetching original images: pre-defined Image Sources, and via a src query string parameter.

You can use both modes simultaneously with a single LibPixel account.

Image Source

An Image Source is the perfect solution for when your images have a common base URL (e.g. a public S3 bucket URL or your own web server), or are stored in a private S3 bucket.

There are two types of image sources: URL and S3.

URL Image Source

To create a URL Image Source simply choose the URL type, enter the base URL, and give it a name.

Example

Your images are stored in a bucket on Amazon S3. A typical image URL might be https://s3.amazonaws.com/my-bucket/avatar.jpg

You enter the base URL https://s3.amazonaws.com/my-bucket/ as the Image Source, and give it the name my-images.

Now, to fetch any image from your bucket via LibPixel, you would use this URL instead of the Amazon one: https://yourdomain.libpx.com/my-images/.

For example, avatar.jpg would be on the following URL: https://yourdomain.libpx.com/my-images/avatar.jpg.

LibPixel would fetch the image from the Image Source, and deliver it to you, having resized or processed it according to the parameters you choose (see below for a list).

S3 Image Source

The S3 image source allows you to access private objects inside an S3 bucket, by entering the bucket name and the S3 region where the bucket is located.

You'll need to generate an IAM user for LibPixel with access to the S3 bucket you want to use. Please do not use your own IAM credentials for LibPixel, or those of a user with more permissions than the minimum required.

To be able to fetch your private objects, the only permission we need is s3:GetObject. An example IAM Policy to allow S3:GetObject on a specific bucket (named libpixel-uploads here, which you must modify to your own bucket name) is:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "LibPixel",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::libpixel-uploader/*"
            ]
        }
    ]
}

If you wish to use the LibPixel Uploader library, you must choose "Enable uploads", and set an ACL (Access Control List) for uploaded images. Set to public-read to make uploaded files publicly accessible through S3, or private to make them accessible only through LibPixel.

For the uploads to work, we need the additional permissions s3:PutObject and s3:PutObjectAcl. For example:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "LibPixel",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": [
                "arn:aws:s3:::libpixel-uploader/*"
            ]
        }
    ]
}

The src parameter

Using the src query string parameter makes the most sense when images are fetched from multiple different domains. A good example is an application or website where users submit image URLs, which you wish to resize or modify before displaying them.

The value of the src parameter needs be escaped correctly (e.g. in JavaScript by using encodeURIComponent). The LibPixel Client Libraries do this automatically.

You must sign your URLs when using the src parameter (see Secure URLs below). This is to prevent third parties from using your LibPixel account for their own purposes.

Example

You want to process an image with the URL https://abcd.somewhere.com/images/header.png.

To fetch the image via LibPixel, you would use something similar to the following URL: https://yourdomain.libpx.com/?src=https://abcd.somewhere.com/images/header.png&signature=5BE46CCBE8525D902F507B299EF98D683441188D

Secure URLs

Secure URLs prevent others from generating LibPixel image URLs on your behalf, which would count toward your usage limits.

Secure URLs contain an additional signature parameter at the end of the query string. Signatures are generated using your private Auth Secret.

By default, signatures are only required when using the src parameter. To enable it for all requests, visit the Settings page and enable Require Authenticated Requests.

Generating Signatures

The easiest way to generate Secure URLs is by using a LibPixel Client Library. However, if one doesn't exist for the programming language you're using, you can generate the signatures yourself.

Steps for generating a signature:

  1. Generate an image URL as normal.
  2. Extract the path and query string from the URL. This is the data you'll be signing. The path must begin with a /, and must at least contain 1 character.
  3. Generate an HMAC-SHA1 in hexadecimal format using your Auth Secret. This is your signature value.
  4. Append a query string parameter signature with the signature value to the end of the original query string.

Notes:

  • Include the ? character between the path and query string components, but only if there is a query string.
  • If you signed a URL without a query string, then you must add a query string to the resulting URL which contains only the signature.
  • For the example https://yourdomain.libpx.com/?src=https://abcd.somewhere.com/images/header.png&width=200, you would sign the string /?src=https://abcd.somewhere.com/images/header.png&width=200.

Image API

The Image API works via query string parameters.

In order to request images of the correct width, height or processed in other ways, you simply add the relevant parameters to the URL. For example, to stretch an image to fill a 200 x 200 pixel box, you would use a URL like this: https://yourdomain.libpx.com/my-images/avatar.jpg?width=200&height=200&mode=stretch.

Each parameter is described below. You can specify the parameters in any order.

width

Specifies the width of the output image in pixels.

If this value is omitted or set to 0 (default) its value will be automatically calculated based on the supplied height value, so that the original image aspect ratio is preserved. If neither width nor height is defined, the original image size is used. And if both width and height are supplied, the image will be resized according to the mode setting.

While there is no maximum value for width, the output image will not exceed 6 megapixels (~2508x2508 if the image is a square). If the output image would exceed the limit, it will be scaled down automatically to the largest supported size.

height

Specifies the height of the output image in pixels.

If this value is omitted or set to 0 (default) its value will be automatically calculated based on the supplied width value, so that the original image aspect ratio is preserved. If neither width nor height is defined, the original image size is used. And if both width and height are supplied, the image will be resized according to the mode setting.

While there is no maximum value for height, the output image will not exceed 6 megapixels (~2508x2508 if the image is a square). If the output image would exceed the limit, it will be scaled down automatically to the largest possible supported size.

mode

Controls the resize mode when both a width and height are specified.

Available modes:

  • fit: Resize to fit within the boundaries defined by the width and height parameters, while maintaining the original aspect ratio. If the output aspect ratio differs from the original, only one of the dimensions (width or height) will equal its set value, while the other will be smaller.
  • crop: Resize to fill the entire area defined by width and height, by maintaining the aspect ratio, but possibly clipping part of the image.
  • stretch: Resize to fill the entire area defined by width and height, by modifying the aspect ratio.

The default mode is fit.

mode=fit
mode=crop
mode=stretch

crop

Allows you to specify which part of the image is used.

To crop an image, you specify four parameters – the origin x and y (which defines the top left of the crop rectangle) and the dimensions w and h (which define the size of the rectangle).

Cropping is applied before other transformations. In particular, the crop values refer to the dimensions of the image before it has been resized. Note also that resizing may cause additional cropping of some part of the image if mode=crop is used.

no crop
crop=100,100,1000,1000
crop=500,500,1000,1000

dpr

Specifies the device pixel ratio, between 0.1 and 10.0.

Acts as a multiplier for both the width and height. For example, using width=320&height=150&dpr=2 is equivalent to width=640&height=300.

This allows you to easily specify an image with the correct resolution for high dpi devices such as iPhones.

The default dpr is 1.0.

dpr=0.75
dpr=1.0
dpr=2.0

blur

Blurs the image by a value relative to the image size, between 0 and 100.

The maximum blur radius (r) in pixels which corresponds to a blur value of 100 is calculated using the following formula for the image width (w) and height (h):

Blur Formula

For a 640x480 pixel image, a blur value of 100 translates into a blur radius of 80 pixels.

This guarantees that the same blur value will result in the same level of blurriness for the same image at different sizes.

The default blur value is 0 (no blur).

blur=0
blur=5
blur=50

brightness

Adjusts the brightness of the image, with values between -100 and 100.

The default value is 0 (no brightness adjustment).

brightness=-15
brightness=0
brightness=15

contrast

Adjusts the contrast of the image, with values between -100 and 100.

The default value is 0 (no contrast adjustment).

contrast=-20
contrast=0
contrast=20

hue

Adjusts the hue of the image, with values between -100 and 100.

The default value is 0 (no hue adjustment).

hue=-80
hue=0
hue=70

saturation

Adjusts the saturation of the image, with values between -100 and 100.

A saturation value of -100 turns the image into grayscale.

The default value is 0 (no saturation adjustment).

saturation=-100
saturation=-60
saturation=0

gamma

Adjusts the gamma of the image, with values between -100 and 100.

The default value is 0 (no gamma adjustment).

gamma=-20
gamma=0
gamma=50

quality

Sets the quality of the output image, with values between 0 and 100.

This setting only affects JPEG images. Higher quality values result in images with a larger file size.

The default quality is 85.

quality=15
quality=50
quality=85

format

Normally images are processed and presented in the same format as the input image. This parameter allows you to force the output image to a particular format.

You can force images to be output as jpeg, png or webp, using format=jpeg, format=png or format=webp.

If the original image has an alpha channel (e.g. transparent PNGs), a white background will be applied if the output format does not support transparency.

png
format=jpeg
format=jpeg&quality=5

upscale

Defines whether the image can be resized past its original size. Set to false to prevent upscaling.

The default upscale value is true.

debug

When LibPixel encounters an error processing an image it may still return a valid image. For example, when using a query string parameter value that's invalid, LibPixel may choose to use a default value or clamp it to the accepted range.

To see an error message instead (as an image), you can set the debug=true query string parameter.

blur=-10&debug=true

Pass through parameters

If you wish to pass query string parameters to your server or image source, just prefix them with an underscore. LibPixel will strip the underscore and pass the parameter along when the image is fetched. For example:

https://yourdomain.libpx.com/my-images/avatar.jpg?width=200&_user=247

would cause LibPixel to fetch the image from the following URL:

https://my.image.source.com/images/avatar.jpg?user=247

(The image source in this case is https://my.image.source.com/images/)

Client libraries

We have official client libraries built for multiple programming languages. All our libraries are open source under the MIT License and available on GitHub.