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.

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